@gavin-hu/my-pi-agent 0.11.4 → 0.13.0

package/extensions/plan/tools.ts

@@ -17,17 +17,17 @@
 
 import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionToolContext } from "@earendil-works/pi-coding-agent";
-import { basename } from "node:path";
 import { Type, type Static } from "typebox";
 import { sanitizeLine } from "../../lib/format.ts";
-import { askHuman } from "../../lib/interaction.ts";
-import { TODO_TOOL } from "../../lib/tool-names.ts";
-import { FULL_SCREEN_OVERLAY, reuseText, toolDetails } from "../../lib/tui/chrome.ts";
+import { lastGoal } from "../../lib/goal-state.ts";
+import { GOAL_TOOL, TODO_TOOL } from "../../lib/tool-names.ts";
+import { lastTodos } from "../../lib/todo-state.ts";
+import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
 import { rejectionLine, reuseCallText, toolCallTitle } from "../../lib/tui/tool.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import { expandHint, GLYPHS } from "../../lib/tui/glyphs.ts";
 import { READ_ONLY_SUMMARY } from "./policy.ts";
-import { feedbackSummary, type PlanAnnotation } from "./feedback.ts";
+import { feedbackSummary } from "./feedback.ts";
 import { ENTER_TOOL, EXIT_TOOL, SET_PLAN_STEPS_TOOL, WRITE_PLAN_TOOL, type PlanRuntime } from "./runtime.ts";
 import {
 	MAX_STEP_LENGTH,
@@ -35,14 +35,17 @@ import {
 	PLAN_OUTLINE,
 	extractPlanSteps,
 	planStepSummary,
+	verificationItem,
 	type PlanStep,
-	type PlanStepSummary,
 	type StepUpdate,
 } from "./steps.ts";
-import { DEFAULT_TODO_MAX, lastTodos, mergeTodos, type TodoMerge } from "./todos.ts";
-import { PlanViewComponent, sanitizePlanText, type PlanViewAction } from "./tui.ts";
+import { basename } from "node:path";
+import { planTitle, type StoredPlan } from "./plans.ts";
+import { DEFAULT_TODO_MAX, mergeTodos, type TodoMerge } from "./todos.ts";
+import { reviewPlan } from "./review.ts";
+import { sanitizePlanText } from "./plan-text.ts";
 import type { EnterPlanModeDetails, ExitPlanModeDetails, SetPlanStepsDetails, WritePlanDetails } from "./types.ts";
-import { createPlanWebReview, type PlanReviewResult, type PlanReviewSession, type PlanWebReview } from "./web.ts";
+import { createPlanWebReview, type PlanWebReview } from "./web.ts";
 
 const ExitPlanModeParams = Type.Object({
 	plan_path: Type.String({
@@ -116,20 +119,21 @@ function preview(plan: string): { body: string; more: number } {
 }
 
 /**
- * One sentence for `write_plan` when the step list is larger than approval can
- * track, so the model can shorten it instead of discovering the cap later.
+ * One sentence when a step is longer than the display cap. The text stays in the
+ * plan file either way; only the todo list and the approval listing shorten it.
  */
-function stepCapNote({ total, elided }: PlanStepSummary): string {
-	const notes: string[] = [];
-	if (total > MAX_STEPS) {
-		notes.push(`the plan has ${total} steps and only the first ${MAX_STEPS} can be seeded or ticked`);
-	}
-	if (elided > 0) {
-		notes.push(
-			`${elided} step${elided === 1 ? " is" : "s are"} longer than ${MAX_STEP_LENGTH} characters and will be shortened in the todo list`,
-		);
-	}
-	return notes.length > 0 ? ` Note: ${notes.join("; ")}.` : "";
+function stepElisionNote(elided: number): string {
+	if (elided === 0) return "";
+	const plural = elided === 1 ? " is" : "s are";
+	return ` Note: ${elided} step${plural} longer than ${MAX_STEP_LENGTH} characters and will be shortened in the todo list.`;
+}
+
+/**
+ * The diagnosis both cap refusals share: a step list longer than approval can
+ * track. Each caller appends the fix that is available from where it stands.
+ */
+function overCap(total: number): string {
+	return `The plan has ${total} top-level steps but approval tracks at most ${MAX_STEPS}.`;
 }
 
 /** "Step 2" or "Steps 1, 2" for a set of step numbers. */
@@ -171,11 +175,12 @@ async function seedTodos(
 	plan: string,
 ): Promise<{ steps: PlanStep[]; merged?: TodoMerge; error?: string }> {
 	const steps = extractPlanSteps(plan);
-	if (steps.length === 0) return { steps };
-	const merged = mergeTodos(lastTodos(ctx.sessionManager.getBranch()), steps, todoMaxItems(pi));
-	// Nothing new to write: every step is already in the list (or the list is
-	// full), so a whole-list rewrite would only churn the todo widget.
-	if (merged.added === 0) return { steps, merged };
+	const verification = verificationItem(plan);
+	if (steps.length === 0 && !verification) return { steps };
+	const merged = mergeTodos(lastTodos(ctx.sessionManager.getBranch()), steps, todoMaxItems(pi), verification);
+	// Nothing new to write: every step (and the verification item) is already in
+	// the list, or the list is full, so a rewrite would only churn the widget.
+	if (merged.added === 0 && merged.trailing !== "added") return { steps, merged };
 	const outcome = await ctx.executeTool(TODO_TOOL, { todos: merged.todos });
 	if (!outcome.isError) return { steps, merged };
 	// The nested call fails both when the tool is unavailable and when it rejects
@@ -185,6 +190,56 @@ async function seedTodos(
 	return { steps, merged, error: firstLine ? sanitizeLine(firstLine) : undefined };
 }
 
+/** What the goal offer did: `recorded` undefined when there was nothing to offer. */
+interface GoalOffer {
+	objective: string;
+	recorded?: boolean;
+	error?: string;
+}
+
+/**
+ * Offer to record the approved plan as the session goal — only when the session
+ * has no goal at all (an active or achieved one is the user's, never replaced) and
+ * the session can ask. The objective is the plan's own `# title`, or the file-name
+ * slug; recording runs through the goal tool, so validation and the widget stay
+ * goal's, and no model turn is spent.
+ */
+async function offerSessionGoal(ctx: ExtensionToolContext, plan: StoredPlan): Promise<GoalOffer> {
+	const objective = planObjective(plan);
+	if (!ctx.hasUI) return { objective };
+	// The branch already carries a goal: leave it alone, and say nothing.
+	if (lastGoal(ctx.sessionManager.getBranch()) !== null) return { objective };
+	const approved = await ctx.ui.confirm("Record this plan as the session goal?", objective);
+	if (!approved) return { objective };
+	const outcome = await ctx.executeTool(GOAL_TOOL, { objective });
+	if (!outcome.isError) return { objective, recorded: true };
+	const part = outcome.result?.content?.find((entry) => entry.type === "text");
+	const firstLine = part?.type === "text" ? part.text.split("\n", 1)[0] : undefined;
+	return { objective, recorded: false, error: firstLine ? sanitizeLine(firstLine) : undefined };
+}
+
+/** The plan's own title: its first `# heading`, else the file-name slug. */
+function planObjective(plan: StoredPlan): string {
+	const heading = /^ {0,3}#\s+(.+)$/m.exec(plan.content)?.[1];
+	const title = heading === undefined ? "" : sanitizeLine(heading).trim();
+	return title || planTitle(basename(plan.path));
+}
+
+/**
+ * One sentence about the plan's verification item, or "" when the plan has none
+ * (or it was already in the list). The item is a todo, not a plan step, so it is
+ * ticked in the list rather than in the file.
+ */
+function verificationNote(merged: TodoMerge | undefined): string {
+	if (merged?.trailing === "added") {
+		return "\nThe plan's verification section is the last todo item; tick it in the todo list, not in the file.";
+	}
+	if (merged?.trailing === "deferred") {
+		return "\nThe plan's verification section did not fit in the full todo list; keep it in mind.";
+	}
+	return "";
+}
+
 /** What the merge did, for the approval message; `steps` is the plan's step count. */
 function mergeSummary(merged: TodoMerge, steps: PlanStep[]): string {
 	const total = steps.length;
@@ -204,103 +259,6 @@ function mergeSummary(merged: TodoMerge, steps: PlanStep[]): string {
 	return ` Merged ${counted} into the todo list${suffix}. ${tick}`;
 }
 
-/** The review choice plus the refinement the user typed in the TUI, if any. */
-interface PlanReviewOutcome {
-	action: PlanViewAction;
-	refinement?: string;
-}
-
-/** A dialog-only choice: post the full plan text, then ask again. Never returned. */
-type ReviewChoice = PlanReviewOutcome | { action: "send" };
-
-/** Prompt shown by the dialog-based refine editor in non-TUI modes. */
-const REFINE_PROMPT = "Refine the plan — what should change? (Enter to save, Esc to cancel)";
-
-/** How much of one step the remote digest shows. */
-const DIGEST_STEP_CHARS = 90;
-
-/**
- * A one-message digest of the plan for a remote review.
- *
- * The file is the primary artifact, but a phone client may never render or open
- * it, and the peer still has to choose approve / refine. The digest carries the
- * title, the step count, and the first few steps; the full text follows as a
- * file or as the fallback message.
- */
-function planReviewDigest(content: string): string {
-	const title = /^#\s+(.+)$/m.exec(content)?.[1]?.trim();
-	const steps = extractPlanSteps(content);
-	const count = steps.length;
-	const head = `Plan${title ? `: ${title}` : ""}${count > 0 ? ` (${count} step${count === 1 ? "" : "s"})` : ""}`;
-	const preview = steps.slice(0, 3).map((step, index) => {
-		const text = step.content.replace(/\s+/g, " ").trim();
-		const shown = text.length > DIGEST_STEP_CHARS ? `${text.slice(0, DIGEST_STEP_CHARS - 1)}…` : text;
-		return `${index + 1}. ${shown}`;
-	});
-	const more = count > preview.length ? `… (${count - preview.length} more)` : "";
-	return [head, ...preview, more, "The full plan is attached above, or sent as text if the file failed."]
-		.filter((line) => line !== "")
-		.join("\n");
-}
-
-/**
- * Ask the user to review the plan file. The TUI opens the scrollable review
- * screen (with an inline refine editor); dialog-capable modes (RPC) fall back
- * to a select plus the refine editor; the caller has already refused when there
- * is no UI.
- */
-async function reviewPlan(
-	ctx: ExtensionToolContext,
-	plan: { path: string; relativePath: string; content: string; bytes: number },
-	previous?: string,
-): Promise<PlanReviewOutcome> {
-	// The first pass sends the file (or the full text when it fails) and the
-	// digest; asking for the full plan re-enters with the text only, then shows
-	// the choices again.
-	let sentFullText = false;
-	for (;;) {
-		const outcome = await askHuman<ReviewChoice>(ctx, {
-			custom: async () => {
-				const outcome = await ctx.ui.custom<PlanReviewOutcome | undefined>(
-					(tui, theme, _keybindings, done) =>
-						new PlanViewComponent({
-							plan,
-							previous,
-							theme,
-							onClose: (action, refinement) => done({ action, refinement }),
-							requestRender: () => tui.requestRender(),
-							viewportRows: () => tui.terminal?.rows,
-							tui,
-						}),
-					FULL_SCREEN_OVERLAY,
-				);
-				return outcome ?? { action: "keep" };
-			},
-			dialogs: async () => {
-				const choice = await ctx.ui.select("Plan mode — what next?", [
-					"Approve and execute",
-					"Send the full plan",
-					"Refine the plan",
-					"Keep planning",
-				]);
-				if (choice === "Approve and execute") return { action: "approve" };
-				if (choice === "Send the full plan") return { action: "send" };
-				if (choice === "Refine the plan") return { action: "refine" };
-				return { action: "keep" };
-			},
-			// A remote turn gets the plan file up front, falling back to the full text;
-			// a local TUI turn ignores both and renders the component. The digest goes
-			// out either way so the choices stay answerable when a phone client does not
-			// render the file bubble.
-			file: sentFullText ? undefined : { path: plan.path, name: basename(plan.relativePath) },
-			body: plan.content,
-			note: sentFullText ? undefined : planReviewDigest(plan.content),
-		});
-		if (outcome.action !== "send") return outcome;
-		sentFullText = true;
-	}
-}
-
 export function registerTools(
 	pi: ExtensionAPI,
 	runtime: PlanRuntime,
@@ -320,7 +278,7 @@ export function registerTools(
 		executionMode: "sequential",
 		// readOnlyHint stays true: entering plan mode changes only the session's
 		// tool set, never files or system state, so it needs no approval.
-		annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+		annotations: { readOnlyHint: true, openWorldHint: false },
 
 		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
 			if (runtime.isEnabled()) {
@@ -384,7 +342,8 @@ export function registerTools(
 			"Save the plan you designed as a markdown file under .pi/plans (project root, or the agent directory outside a " +
 			"repository). Write the complete plan, not a summary, in this outline so it is consistent and scannable:\n\n" +
 			`${PLAN_OUTLINE}\n\n` +
-			"Returns the path to pass to exit_plan_mode; plan_path overwrites an existing file when refining.",
+			"Returns the path to pass to exit_plan_mode; plan_path overwrites an existing file when refining. " +
+			`A plan with more than ${MAX_STEPS} top-level steps in its Steps section is refused, so approval never drops steps it cannot track.`,
 		promptSnippet: "Save the designed plan as a markdown file under .pi/plans.",
 		promptGuidelines: [
 			"While plan mode is active, write the full plan with write_plan, then call exit_plan_mode with the returned path.",
@@ -405,6 +364,21 @@ export function registerTools(
 				};
 			}
 			const args = params as WritePlanArgs;
+			const summary = planStepSummary(args.content);
+			if (summary.total > MAX_STEPS) {
+				// Refuse before writing: a note after the fact arrives once the file exists and
+				// the review has listed every step, so the overflow is already lost.
+				return {
+					content: [
+						{
+							type: "text",
+							text: `${overCap(summary.total)} Nothing was written; group the steps (one outcome each, sub-bullets for detail) and call write_plan again.`,
+						},
+					],
+					details: undefined,
+					isError: true,
+				};
+			}
 			try {
 				const file = await runtime.plans.write(ctx.cwd, {
 					title: args.title,
@@ -416,7 +390,7 @@ export function registerTools(
 					content: [
 						{
 							type: "text",
-							text: `Wrote the plan to ${file.relativePath}. Call exit_plan_mode with plan_path: ${file.path}${stepCapNote(planStepSummary(args.content))}`,
+							text: `Wrote the plan to ${file.relativePath}. Call exit_plan_mode with plan_path: ${file.path}${stepElisionNote(summary.elided)}`,
 						},
 					],
 					details: { path: file.path, relativePath: file.relativePath, bytes: file.bytes } satisfies WritePlanDetails,
@@ -464,9 +438,9 @@ export function registerTools(
 		executionMode: "sequential",
 		// readOnlyHint stays true: it writes no files, and the review dialog inside
 		// execute is the human gate, so an outer prompt would only double-ask.
-		annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+		annotations: { readOnlyHint: true, openWorldHint: false },
 
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			const planPath = (params as ExitPlanModeArgs).plan_path.trim();
 
 			if (!runtime.isEnabled()) {
@@ -477,7 +451,7 @@ export function registerTools(
 				};
 			}
 
-			let file = await runtime.plans.read(ctx.cwd, planPath);
+			const file = await runtime.plans.read(ctx.cwd, planPath);
 			if (!file) {
 				return {
 					content: [
@@ -491,6 +465,27 @@ export function registerTools(
 				};
 			}
 
+			const total = planStepSummary(file.content).total;
+			if (total > MAX_STEPS) {
+				// A hand-edited or older plan file can still be over the cap; refuse it here
+				// too, so approval never seeds a list it cannot hold in full.
+				return {
+					content: [
+						{
+							type: "text",
+							text: `${overCap(total)} It was not presented for approval; call write_plan with plan_path to group the steps, then exit_plan_mode again.`,
+						},
+					],
+					details: {
+						approved: false,
+						plan: file.content,
+						planPath: file.path,
+						relativePath: file.relativePath,
+					} satisfies ExitPlanModeDetails,
+					isError: true,
+				};
+			}
+
 			if (!ctx.hasUI) {
 				return {
 					content: [
@@ -510,117 +505,58 @@ export function registerTools(
 				};
 			}
 
-			// What the last review showed this file, so this one can mark the changes.
-			// Mark before presenting: the next review compares against what is on
-			// screen now, not against a revision the user never saw.
-			let presentedPrevious: string | undefined;
-			const present = (candidate: { path: string; relativePath: string; content: string; bytes: number }) => {
-				const previous = runtime.reviewed(candidate.path);
-				runtime.markReviewed(candidate.path, candidate.content);
-				presentedPrevious = previous;
-				return reviewPlan(ctx, candidate, previous);
-			};
-
-			let outcome = await present(file);
-			// Comments carried by a browser approval, reported alongside the approval.
-			let browserComments: PlanAnnotation[] = [];
-			// Review, refine, and browser review all loop back here until the user
-			// approves, keeps planning, or a refinement is handed to the model. The
-			// dialog-based refine editor carries no text from the review screen, so an
-			// empty or cancelled editor returns to the review instead of being reported
-			// as "not approved".
-			for (;;) {
-				if (outcome.action === "browser") {
-					// The review screen that produced this choice already marked the
-					// content it showed, so the page compares against that baseline.
-					const session: PlanReviewSession | undefined = await web
-						.start(ctx.cwd, file, { canApprove: true, previous: presentedPrevious })
-						.catch(() => undefined);
-					if (!session) {
-						ctx.ui.notify("Plan review: could not start the browser review server.", "error");
-						outcome = await present(file);
-						continue;
-					}
-					ctx.ui.notify(`Plan review: opened ${session.url}`, "info");
-					const result: PlanReviewResult = await session.done;
-					await session.close();
-					if (result.status === "approved") {
-						// Approve from the browser is the TUI's approve: keep the comments it
-						// carried and fall through to the shared approval path below.
-						file = result.plan;
-						browserComments = result.annotations;
-						outcome = { action: "approve" };
-						continue;
-					}
-					if (result.status === "saved") {
-						// The comments are already in the file; hand them back as a refinement so
-						// the model revises the same plan and calls exit_plan_mode again.
-						const refinement = feedbackSummary(result.annotations) || "See the review comments in the plan file.";
-						return {
-							content: [
-								{
-									type: "text",
-									text: `The user reviewed the plan in the browser and left feedback:\n${refinement}\nStay in plan mode, revise the plan (write_plan, reusing plan_path), then call exit_plan_mode again.`,
-								},
-							],
-							details: {
-								approved: false,
-								plan: result.plan.content,
-								planPath: result.plan.path,
-								relativePath: result.plan.relativePath,
-								refined: true,
-								refinement,
-							} satisfies ExitPlanModeDetails,
-						};
-					}
-					// Cancelled or the tab closed: re-read the file and review again.
-					file = (await runtime.plans.read(ctx.cwd, file.path)) ?? file;
-					outcome = await present(file);
-					continue;
-				}
-				if (outcome.action === "refine" && !outcome.refinement) {
-					const refinement = (await ctx.ui.editor(REFINE_PROMPT, ""))?.trim();
-					if (refinement) outcome = { action: "refine", refinement };
-					else outcome = await present(file);
-					continue;
-				}
-				if (outcome.action === "refine") {
-					const refinement = outcome.refinement ?? "";
-					return {
-						content: [
-							{
-								type: "text",
-								text: `The user asked to refine the plan: ${refinement}\nStay in plan mode, revise the plan (write_plan, reusing plan_path), then call exit_plan_mode again.`,
-							},
-						],
-						details: {
-							approved: false,
-							plan: file.content,
-							planPath: file.path,
-							relativePath: file.relativePath,
-							refined: true,
-							refinement,
-						} satisfies ExitPlanModeDetails,
-					};
-				}
-				if (outcome.action !== "approve") {
-					return {
-						content: [
-							{ type: "text", text: "Plan not approved. Stay in plan mode, ask what to change, and revise the plan." },
-						],
-						details: {
-							approved: false,
-							plan: file.content,
-							planPath: file.path,
-							relativePath: file.relativePath,
-						} satisfies ExitPlanModeDetails,
-					};
-				}
-				break;
+			// One decision, however the session is attached; `review.ts` owns the loop,
+			// the baseline, and closing the browser review when the turn is aborted.
+			const decision = await reviewPlan({
+				ctx,
+				web,
+				plans: runtime.plans,
+				baselines: runtime,
+				plan: file,
+				signal,
+			});
+
+			if (decision.action === "refine") {
+				// A browser save already wrote its comments into the file; either way the
+				// model revises the same plan and presents it again.
+				const feedback = decision.fromBrowser
+					? `The user reviewed the plan in the browser and left feedback:\n${decision.refinement}`
+					: `The user asked to refine the plan: ${decision.refinement}`;
+				return {
+					content: [
+						{
+							type: "text",
+							text: `${feedback}\nStay in plan mode, revise the plan (write_plan, reusing plan_path), then call exit_plan_mode again.`,
+						},
+					],
+					details: {
+						approved: false,
+						plan: decision.plan.content,
+						planPath: decision.plan.path,
+						relativePath: decision.plan.relativePath,
+						refined: true,
+						refinement: decision.refinement,
+						annotations: decision.comments.length > 0 ? decision.comments : undefined,
+					} satisfies ExitPlanModeDetails,
+				};
+			}
+			if (decision.action === "keep") {
+				return {
+					content: [
+						{ type: "text", text: "Plan not approved. Stay in plan mode, ask what to change, and revise the plan." },
+					],
+					details: {
+						approved: false,
+						plan: decision.plan.content,
+						planPath: decision.plan.path,
+						relativePath: decision.plan.relativePath,
+					} satisfies ExitPlanModeDetails,
+				};
 			}
 
 			runtime.disable(ctx);
-			const { steps, merged, error } = await seedTodos(pi, ctx, file.content);
+			const { steps, merged, error } = await seedTodos(pi, ctx, decision.plan.content);
+			const goal = await offerSessionGoal(ctx, decision.plan);
 			const listing =
 				steps.length > 0
 					? `\n\n${steps
@@ -635,21 +571,29 @@ export function registerTools(
 						: merged
 							? mergeSummary(merged, steps)
 							: ` Could not read the todo list. Record these steps with the todo tool before you start, and tick them off with ${SET_PLAN_STEPS_TOOL}.`;
-			const browserNote = browserComments.length
-				? `\n\nThe user approved from the browser review with these comments:\n${feedbackSummary(browserComments)}`
+			const verification = verificationNote(merged);
+			const goalNote =
+				goal.recorded === undefined
+					? ""
+					: goal.recorded
+						? ` Recorded the session goal: ${goal.objective}.`
+						: ` Could not record the session goal: ${goal.error ?? "unknown error"}. Use the goal tool to set it.`;
+			const browserNote = decision.comments.length
+				? `\n\nThe user approved from the browser review with these comments:\n${feedbackSummary(decision.comments)}`
 				: "";
 			return {
 				content: [
 					{
 						type: "text",
-						text: `Plan approved. Plan mode is off and write access is restored. The plan file ${file.relativePath} is the source of truth; follow its steps.${browserNote}${tail}${listing}`,
+						text: `Plan approved. Plan mode is off and write access is restored. The plan file ${decision.plan.relativePath} is the source of truth; follow its steps.${browserNote}${tail}${verification}${goalNote}${listing}`,
 					},
 				],
 				details: {
 					approved: true,
-					plan: file.content,
-					planPath: file.path,
-					relativePath: file.relativePath,
+					plan: decision.plan.content,
+					planPath: decision.plan.path,
+					relativePath: decision.plan.relativePath,
+					annotations: decision.comments.length > 0 ? decision.comments : undefined,
 				} satisfies ExitPlanModeDetails,
 			};
 		},