@gavin-hu/my-pi-agent 0.17.0 → 0.19.0

package/extensions/plan/review-prompt.ts

@@ -0,0 +1,93 @@
+/**
+ * Pure rendering and parsing for the compact remote plan review.
+ *
+ * The prompt and its reply share one action table, so changing a number or a
+ * localized label cannot leave the parser behind. File delivery and the review
+ * lifecycle stay in `review.ts`.
+ */
+
+import type { InteractionLanguage } from "../../lib/interaction.ts";
+import { extractPlanSteps } from "./steps.ts";
+
+/** The actions the compact prompt can resolve without a refinement. */
+export type PlanReviewAction = "approve" | "keep" | "cancel";
+
+/** One editor reply: an action, or free text the model should apply. */
+export type PlanReviewReply =
+	| { action: "approve" }
+	| { action: "keep" }
+	| { action: "cancel" }
+	| { action: "refine"; refinement: string };
+
+interface ReviewAction {
+	key: string;
+	action: PlanReviewAction;
+	zh: string;
+	en: string;
+	words: readonly string[];
+}
+
+/** The action line and the parser read this one table, in display order. */
+const REVIEW_ACTIONS: readonly ReviewAction[] = [
+	{ key: "1", action: "approve", zh: "批准", en: "approve", words: ["approve", "批准", "同意"] },
+	{
+		key: "2",
+		action: "keep",
+		zh: "继续规划",
+		en: "keep planning",
+		words: ["keep", "keep planning", "继续", "继续规划"],
+	},
+	{ key: "3", action: "cancel", zh: "退出", en: "exit", words: ["exit", "cancel", "quit", "退出", "取消"] },
+];
+
+/** How much of one step the remote digest shows. */
+const DIGEST_STEP_CHARS = 90;
+
+/**
+ * One compact remote prompt: title, first steps, mode status, and the action
+ * line. The plan file is sent before it; a non-action reply refines the plan.
+ */
+export function planReviewPrompt(content: string, language: InteractionLanguage, attached: boolean): string {
+	const title = /^#\s+(.+)$/m.exec(content)?.[1]?.trim();
+	const steps = extractPlanSteps(content);
+	const count = steps.length;
+	const head =
+		language === "zh"
+			? `计划${title ? `：${title}` : ""}${count > 0 ? `（${count} 步）` : ""}`
+			: `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
+			? language === "zh"
+				? `… 还有 ${count - preview.length} 步`
+				: `… (${count - preview.length} more)`
+			: "";
+	const status = language === "zh" ? "Plan 模式开启，写入已关闭。" : "Plan mode is on — write access is off.";
+	const attachment = attached ? (language === "zh" ? "计划已在上方。" : "The plan is above.") : "";
+	const choices = REVIEW_ACTIONS.map((action) => `${action.key} ${action[language]}`).join(
+		language === "zh" ? "，" : ", ",
+	);
+	const actions =
+		language === "zh"
+			? `回复 ${choices}；或直接输入修改意见（想做别的先退出或批准）。`
+			: `Reply ${choices} — or type feedback to revise. To ask something else, exit or approve first.`;
+	return [head, ...preview, more, status, attachment, actions].filter((line) => line !== "").join("\n");
+}
+
+/**
+ * Parse the one editor reply. Only an exact number or action word is an action;
+ * any other non-empty text is a refinement request.
+ */
+export function parsePlanReviewReply(raw: string): PlanReviewReply {
+	const text = raw.trim();
+	if (text === "") return { action: "cancel" };
+	const key = text.toLowerCase();
+	for (const action of REVIEW_ACTIONS) {
+		if (key === action.key || action.words.includes(key)) return { action: action.action };
+	}
+	return { action: "refine", refinement: text };
+}

package/extensions/plan/review.ts

@@ -1,9 +1,9 @@
 /**
  * The plan review gate: ask the human about a plan file and return one decision.
  *
- * A review has three presentations — the scrollable TUI screen, a select plus
- * editor for dialog-only modes, and a remote turn's plan file plus digest — and
- * one optional browser server. This module owns the loop that switches between
+ * A review has three presentations — the scrollable TUI screen, a dialog-only
+ * editor, and a remote turn's compact editor prompt — and one optional browser
+ * server. This module owns the loop that switches between
  * them, so `exit_plan_mode` and `/plan review` share one lifecycle and only map
  * the returned {@link ReviewDecision} to their own result.
  *
@@ -12,14 +12,14 @@
  * signal reaches the browser server so an aborted turn closes it.
  */
 
-import type { ExtensionToolContext } from "@earendil-works/pi-coding-agent";
 import { basename } from "node:path";
-import { askHuman } from "../../lib/interaction.ts";
+import type { ExtensionToolContext } from "@earendil-works/pi-coding-agent";
+import { askHuman, isRemoteTurn, remoteLanguage } from "../../lib/interaction.ts";
 import { FULL_SCREEN_OVERLAY } from "../../lib/tui/chrome.ts";
 import { feedbackSummary, type PlanAnnotation } from "./feedback.ts";
 import type { PlanStore, StoredPlan } from "./plans.ts";
 import type { SectionDigest } from "./plan-text.ts";
-import { extractPlanSteps } from "./steps.ts";
+import { planReviewPrompt, parsePlanReviewReply } from "./review-prompt.ts";
 import { PlanViewComponent, type PlanViewAction } from "./tui.ts";
 import type { PlanReviewResult, PlanReviewSession, PlanWebReview } from "./web.ts";
 
@@ -29,9 +29,6 @@ interface PlanReviewChoice {
 	refinement?: string;
 }
 
-/** A dialog-only choice: post the full plan text, then ask again. Never returned. */
-type ReviewChoice = PlanReviewChoice | { action: "send" };
-
 /** What a review decided, and the plan state it decided on. */
 export type ReviewDecision =
 	| { action: "approve"; plan: StoredPlan; comments: PlanAnnotation[] }
@@ -78,98 +75,45 @@ const REFINE_PROMPT = "Refine the plan — what should change? (Enter to save, E
  */
 export const PLAN_REVIEW_TIMEOUT_MS = 600_000;
 
-/** 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,
-		"Plan mode is on — write access is off. Choose “Exit plan mode” to leave without approving.",
-		"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; a remote turn gets the plan file and a digest
- * first. Asking for the full plan re-enters with the text only, then shows the
- * choices again.
+ * Ask the user to review the plan file. The TUI opens the scrollable screen;
+ * dialog-capable modes (RPC/WeChat) get one editor prompt. A reply that is not an
+ * action is a refinement.
  */
 async function askPlanReview(
 	ctx: ExtensionToolContext,
 	plan: StoredPlan,
 	baseline: SectionDigest[] | undefined,
 ): Promise<PlanReviewChoice> {
-	let sentFullText = false;
-	for (;;) {
-		const outcome = await askHuman<ReviewChoice>(ctx, {
-			custom: async () => {
-				const choice = await ctx.ui.custom<PlanReviewChoice | undefined>(
-					(tui, theme, _keybindings, done) =>
-						new PlanViewComponent({
-							plan,
-							baseline,
-							theme,
-							onClose: (action, refinement) => done({ action, refinement }),
-							requestRender: () => tui.requestRender(),
-							viewportRows: () => tui.terminal?.rows,
-							tui,
-						}),
-					FULL_SCREEN_OVERLAY,
-				);
-				return choice ?? { 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 (stay in plan mode)",
-					"Exit plan mode (discard)",
-				]);
-				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" };
-				if (choice === "Keep planning (stay in plan mode)") return { action: "keep" };
-				// Dismissing the plan gate means leaving plan mode, not silently staying
-				// in it. The explicit Keep choice above is the only way to stay.
-				return { action: "cancel" };
-			},
-			// 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),
-			timeoutMs: PLAN_REVIEW_TIMEOUT_MS,
-		});
-		if (outcome.action !== "send") return outcome;
-		sentFullText = true;
-	}
+	const language = remoteLanguage(ctx) ?? "en";
+	const remote = isRemoteTurn(ctx);
+	return askHuman<PlanReviewChoice>(ctx, {
+		custom: async () => {
+			const choice = await ctx.ui.custom<PlanReviewChoice | undefined>(
+				(tui, theme, _keybindings, done) =>
+					new PlanViewComponent({
+						plan,
+						baseline,
+						theme,
+						onClose: (action, refinement) => done({ action, refinement }),
+						requestRender: () => tui.requestRender(),
+						viewportRows: () => tui.terminal?.rows,
+						tui,
+					}),
+				FULL_SCREEN_OVERLAY,
+			);
+			return choice ?? { action: "keep" };
+		},
+		dialogs: async () => {
+			const answer = await ctx.ui.editor(planReviewPrompt(plan.content, language, remote), "");
+			return parsePlanReviewReply(answer ?? "");
+		},
+		// The full plan is the artifact under review, so it goes out before the
+		// choices; if the upload fails, the same text is the fallback.
+		file: { path: plan.path, name: basename(plan.relativePath) },
+		body: plan.content,
+		timeoutMs: PLAN_REVIEW_TIMEOUT_MS,
+	});
 }
 
 /** How a browser review may decide, and what to report when it opens. */
@@ -182,6 +126,11 @@ export interface BrowserReviewOptions {
 	signal?: AbortSignal;
 	/** Called once the server is listening and the browser was opened. */
 	onOpened?: (session: PlanReviewSession) => void;
+	/**
+	 * Called when a shared reviewer's post lands, so the owner learns about it where
+	 * they are waiting: the page updates itself, the terminal has to be told.
+	 */
+	onReviewerComment?: (author: string, count: number) => void;
 }
 
 /**
@@ -196,7 +145,12 @@ export async function runBrowserReview(
 ): Promise<PlanReviewResult | undefined> {
 	if (options.signal?.aborted) return { status: "cancelled" };
 	const session = await web
-		.start(cwd, plan, { canApprove: options.canApprove, baseline: options.baseline, signal: options.signal })
+		.start(cwd, plan, {
+			canApprove: options.canApprove,
+			baseline: options.baseline,
+			signal: options.signal,
+			...(options.onReviewerComment === undefined ? {} : { onReviewerComment: options.onReviewerComment }),
+		})
 		.catch(() => undefined);
 	if (!session) return undefined;
 	options.onOpened?.(session);
@@ -242,6 +196,8 @@ export async function reviewPlan(options: ReviewPlanOptions): Promise<ReviewDeci
 			baseline,
 			signal,
 			onOpened: (session) => ctx.ui.notify(`Plan review: opened ${session.url}`, "info"),
+			onReviewerComment: (author, count) =>
+				ctx.ui.notify(`Plan review: @${author} posted ${count === 1 ? "a comment" : `${count} comments`}.`, "info"),
 		});
 		if (!result) {
 			ctx.ui.notify("Plan review: could not start the browser review server.", "error");

package/extensions/plan/runtime.ts

@@ -4,15 +4,15 @@
  * Enabling plan mode removes every tool the policy does not consider read-only
  * from the active set and activates the plan-mode control tools: `exit_plan_mode`
  * (present the plan for approval) and `write_plan` (save the plan artifact under
- * `.pi/plans`). Disabling restores exactly what it hid. The enabled flag is
+ * the plans directory). Disabling restores exactly what it hid. The enabled flag is
  * persisted as a custom session entry so `/resume` and `/tree` follow the
  * branch, and it is also mirrored into the footer status. The review baseline
  * travels the same way, as one digest per heading section, so the changed-section
  * markers survive a resume too.
  *
  * `write_plan` is the one sanctioned write while planning. The read-only guard
- * in `index.ts` permits a control tool only when the registered tool is this
- * extension's own (matched by source path), so a same-named tool from another
+ * in `index.ts` permits plan's own tools only when the registered tool is this
+ * extension's (matched by source path), so a same-named tool from another
  * extension cannot borrow the exemption.
  */
 
@@ -48,9 +48,17 @@ export const BASELINE_TYPE = "plan-baseline";
 /** Longest plan-file basename shown in the footer chip. */
 const STATUS_NAME_LENGTH = 28;
 
-/** Tools plan mode activates itself; the guard permits only this extension's own. */
+/** Tools plan mode activates itself. */
 const CONTROL_TOOLS = [EXIT_TOOL, CANCEL_TOOL, WRITE_PLAN_TOOL];
 
+/**
+ * Tools the read-only guard exempts when this extension registered them.
+ * `enter_plan_mode` is here only so a call already in flight when plan mode came on
+ * is answered by the tool ("already in plan mode"); the policy still denies it, so
+ * it stays hidden while planning.
+ */
+const OWNED_TOOLS = [...CONTROL_TOOLS, ENTER_TOOL];
+
 export interface PlanRuntime {
 	/** Whether plan mode is currently on. */
 	isEnabled(): boolean;
@@ -61,8 +69,8 @@ export interface PlanRuntime {
 	restore(ctx: ExtensionContext): void;
 	/** Plan-file storage for `write_plan` and `exit_plan_mode`. */
 	plans: PlanStore;
-	/** Whether `toolName` is a plan-owned control tool (not a same-named impostor). */
-	isControlTool(toolName: string): boolean;
+	/** Whether `toolName` is one of plan's own tools (not a same-named impostor) the read-only guard exempts. */
+	isOwnTool(toolName: string): boolean;
 	/** Path of the most recently written plan, for the footer chip. */
 	lastPlanPath(): string | undefined;
 	/** Remember a written plan and repaint the footer. */
@@ -159,11 +167,15 @@ export function createPlanRuntime(
 
 	const plans = createPlanStore(pi);
 
-	const isControlTool = (toolName: string): boolean => {
-		if (!CONTROL_TOOLS.includes(toolName)) return false;
+	/**
+	 * Whether `toolName` is plan's own registration, matched by the entry path the
+	 * host recorded. Older hosts may not record a source; only a recorded mismatch
+	 * is rejected.
+	 */
+	const isOwnTool = (toolName: string): boolean => {
+		if (!OWNED_TOOLS.includes(toolName)) return false;
 		const info = pi.getAllTools().find((tool) => tool.name === toolName);
 		const source = info?.sourceInfo?.path;
-		// Older hosts may not record a source; only reject a recorded mismatch.
 		return source === undefined || options.entryPath === undefined || samePath(source, options.entryPath);
 	};
 
@@ -241,7 +253,7 @@ export function createPlanRuntime(
 			if (ctx) setStatus(ctx);
 		},
 		plans,
-		isControlTool,
+		isOwnTool,
 		lastPlanPath: () => lastPlanPath,
 		setLastPlan: (ctx, path) => {
 			lastPlanPath = path;

package/extensions/plan/sections.ts

@@ -0,0 +1,112 @@
+/**
+ * Plan-document sections (pure).
+ *
+ * One fence-aware scan of a plan's markdown: the review screen navigates by
+ * section, `set_plan_steps` looks up `## Steps`, a carried comment finds the
+ * block it belongs to, and the browser outline lists the same headings. A second
+ * scanner would disagree about a heading inside a fence, so every reader goes
+ * through this module.
+ *
+ * The scan is deliberately smaller than CommonMark: a heading is up to three
+ * leading spaces, a space after the hashes, and an optional closing run; a fence
+ * is three backticks or tildes anywhere a fence may start. Inside a fence
+ * nothing is a heading, which is what keeps a `# comment` in a shell example out
+ * of the outline. Every section keeps its raw source lines, so a caller can edit
+ * exactly what it read.
+ */
+
+/** A heading-delimited chunk of a plan, for navigation and in-place edits. */
+export interface PlanSection {
+	/** Plain heading text, or `""` for the content before the first heading. */
+	title: string;
+	/** The section's markdown, including its heading line. */
+	text: string;
+	/** 0-based source line of the section's heading (0 for the preamble). */
+	line: number;
+	/** Heading level, or 0 for the preamble before the first heading. */
+	level: number;
+}
+
+/**
+ * A markdown heading outside a fence, capturing its level and text: up to three
+ * leading spaces, a space after the hashes, and a closing hash run only when a
+ * space separates it. Shared with the block model, so the section split and the
+ * browser outline read a heading line the same way, and `## C#` keeps its title.
+ */
+export const HEADING = /^ {0,3}(#{1,6})\s+(.*?)(?:\s+#+)?\s*$/;
+
+/**
+ * A markdown code-fence opener or closer (backticks or tildes). Shared with the
+ * block model: a tab-indented fence is prose for both parsers, never code for one
+ * and prose for the other.
+ */
+export const FENCE = /^ {0,3}(`{3,}|~{3,})/;
+
+/**
+ * A heading or step label as the review surfaces compare it: inline emphasis and
+ * code removed, whitespace collapsed. Exported so a renderer labels an outline
+ * entry the same way {@link extractSections} labels its section, which is what
+ * lets the browser mark a changed section.
+ */
+export function normalizeHeadingText(text: string): string {
+	return text
+		.replace(/\*\*([^*]+)\*\*/g, "$1")
+		.replace(/\*([^*]+)\*/g, "$1")
+		.replace(/(?<![A-Za-z0-9_])_([^_]+)_(?![A-Za-z0-9_])/g, "$1")
+		.replace(/`([^`]+)`/g, "$1")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+/**
+ * Sections of a plan, split at heading lines outside code fences. The content
+ * before the first heading is a section titled `""`. Pi's `Markdown` renderer
+ * exposes no source-line map, so the review screen renders these chunks
+ * separately to know where each section begins.
+ */
+export function extractSections(plan: string): PlanSection[] {
+	const sections: PlanSection[] = [];
+	let current: PlanSection | undefined;
+	let fence: string | undefined;
+
+	const flush = (): void => {
+		if (current && (current.title !== "" || current.text.trim() !== "")) sections.push(current);
+		current = undefined;
+	};
+
+	plan.split("\n").forEach((line, index) => {
+		const fenceMatch = line.match(FENCE);
+		if (fenceMatch) {
+			if (fence === undefined) fence = fenceMatch[1][0];
+			else if (fence === fenceMatch[1][0]) fence = undefined;
+		} else if (fence === undefined) {
+			const heading = line.match(HEADING);
+			if (heading) {
+				flush();
+				current = { title: normalizeHeadingText(heading[2]), text: line, line: index, level: heading[1].length };
+				return;
+			}
+		}
+		if (current === undefined) current = { title: "", text: line, line: 0, level: 0 };
+		else current.text += `\n${line}`;
+	});
+
+	flush();
+	return sections;
+}
+
+/**
+ * One key per section that tells two identically titled headings apart: the title
+ * and which occurrence of it this is, in document order. The review pairs a
+ * baseline digest with the section it belongs to by it, and the feedback codec
+ * matches a comment's section across a rewrite, so a second `## Notes` never
+ * collects the first one's lines.
+ */
+export function sectionKeys(sections: readonly { title: string }[]): string[] {
+	const seen = new Map<string, number>();
+	return sections.map((section) => {
+		const occurrence = seen.get(section.title) ?? 0;
+		seen.set(section.title, occurrence + 1);
+		return `${occurrence}\u0000${section.title}`;
+	});
+}