@gavin-hu/my-pi-agent 0.16.0 → 0.18.0

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,15 @@
  * 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 { PlanUnit } from "../../lib/plans/team.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 +30,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[] }
@@ -44,7 +42,9 @@ export type ReviewDecision =
 			/** True when the request came from the browser, which is reported differently. */
 			fromBrowser: boolean;
 	  }
-	| { action: "keep"; plan: StoredPlan };
+	| { action: "keep"; plan: StoredPlan }
+	/** Leave plan mode without approving; the plan file stays for a later review. */
+	| { action: "cancel"; plan: StoredPlan };
 
 /** What the previous review showed, so this one can mark what changed. */
 export interface ReviewBaselines {
@@ -64,95 +64,68 @@ export interface ReviewPlanOptions {
 	plan: StoredPlan;
 	/** Aborting the turn closes a browser review and returns the plan unapproved. */
 	signal?: AbortSignal;
+	/** The split approval would write, so the screen shows what is being approved. */
+	split?: ReviewSplit;
+}
+
+/** A validated split, as the review screen displays it. */
+export interface ReviewSplit {
+	lead: string;
+	units: readonly PlanUnit[];
+	verdict: "pair" | "team";
 }
 
 /** 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;
-
-/** The refinement request used when a browser save carried no comments. */
-const NO_BROWSER_COMMENTS = "See the review comments in the plan file.";
-
 /**
- * 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.
+ * How long a remote review waits for its answer. Much longer than a plain dialog's
+ * bound, because the human has to read the plan first and a phone is a slow place
+ * to do it; an expiry here also ends plan mode, so it must not be easy to hit.
  */
-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");
-}
+export const PLAN_REVIEW_TIMEOUT_MS = 600_000;
 
 /**
- * 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,
+	split: ReviewSplit | 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",
-				]);
-				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;
-	}
+	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,
+						...(split === undefined ? {} : { split }),
+						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. */
@@ -165,6 +138,13 @@ 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;
+	/** A line the page shows the owner, such as why approval belongs in the terminal. */
+	note?: string;
 }
 
 /**
@@ -179,7 +159,13 @@ 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.note === undefined ? {} : { note: options.note }),
+			...(options.onReviewerComment === undefined ? {} : { onReviewerComment: options.onReviewerComment }),
+		})
 		.catch(() => undefined);
 	if (!session) return undefined;
 	options.onOpened?.(session);
@@ -196,7 +182,7 @@ export async function runBrowserReview(
  * cancelled returns to the screen it was opened from.
  */
 export async function reviewPlan(options: ReviewPlanOptions): Promise<ReviewDecision> {
-	const { ctx, web, plans, baselines, signal } = options;
+	const { ctx, web, plans, baselines, signal, split } = options;
 	let plan = options.plan;
 	for (;;) {
 		// An aborted turn has nobody left to answer the screen.
@@ -204,11 +190,12 @@ export async function reviewPlan(options: ReviewPlanOptions): Promise<ReviewDeci
 		// Read the baseline before the screen and mark it after, so what the next
 		// review compares against is the content this one actually showed.
 		const baseline = baselines.reviewed(plan.path);
-		const choice = await askPlanReview(ctx, plan, baseline);
+		const choice = await askPlanReview(ctx, plan, baseline, split);
 		baselines.markReviewed(plan.path, plan.content);
 
 		if (choice.action === "approve") return { action: "approve", plan, comments: [] };
 		if (choice.action === "keep") return { action: "keep", plan };
+		if (choice.action === "cancel") return { action: "cancel", plan };
 		if (choice.action === "refine") {
 			const refinement = choice.refinement ?? (await ctx.ui.editor(REFINE_PROMPT, ""))?.trim();
 			// An empty or cancelled editor returns to the review screen instead of
@@ -219,11 +206,22 @@ export async function reviewPlan(options: ReviewPlanOptions): Promise<ReviewDeci
 		// An unrecognized action keeps planning rather than opening a server.
 		if (choice.action !== "browser") return { action: "keep", plan };
 
+		// A split section exists only after approval, and the page anchors comments to
+		// source lines, so a page cannot show — or approve — a plan it cannot carry.
+		// The terminal review is where the split is approved.
+		const splitNote =
+			split === undefined
+				? undefined
+				: "This plan has a split, which the page cannot show; approve it in the terminal review.";
+		if (splitNote !== undefined) ctx.ui.notify(splitNote, "info");
 		const result = await runBrowserReview(web, ctx.cwd, plan, {
-			canApprove: true,
+			canApprove: split === undefined,
+			...(splitNote === undefined ? {} : { note: splitNote }),
 			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");
@@ -231,13 +229,15 @@ export async function reviewPlan(options: ReviewPlanOptions): Promise<ReviewDeci
 		}
 		if (result.status === "approved") return { action: "approve", plan: result.plan, comments: result.annotations };
 		if (result.status === "saved") {
-			return {
-				action: "refine",
-				plan: result.plan,
-				refinement: feedbackSummary(result.annotations) || NO_BROWSER_COMMENTS,
-				comments: result.annotations,
-				fromBrowser: true,
-			};
+			// A save with no comments asks for nothing, so it returns to the screen the
+			// way an empty refine editor does, instead of reporting a refinement nobody
+			// wrote.
+			const refinement = feedbackSummary(result.annotations);
+			if (!refinement) {
+				plan = result.plan;
+				continue;
+			}
+			return { action: "refine", plan: result.plan, refinement, comments: result.annotations, fromBrowser: true };
 		}
 		// Cancelled or the tab closed: the file may have been rewritten underneath,
 		// so re-read it before showing the screen again.

package/extensions/plan/runtime.ts

@@ -4,7 +4,7 @@
  * 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
@@ -32,6 +32,8 @@ import type { PlanModeEntry, ReviewBaselineEntry } from "./types.ts";
 
 /** Tool the model calls to leave plan mode after approval. */
 export const EXIT_TOOL = "exit_plan_mode";
+/** Tool the model calls to leave plan mode without approving. */
+export const CANCEL_TOOL = "cancel_plan_mode";
 /** Tool the model calls to ask to enter plan mode. */
 export const ENTER_TOOL = PLAN_ENTER_TOOL;
 /** Tool the model calls to save the plan artifact. */
@@ -47,7 +49,7 @@ export const BASELINE_TYPE = "plan-baseline";
 const STATUS_NAME_LENGTH = 28;
 
 /** Tools plan mode activates itself; the guard permits only this extension's own. */
-const CONTROL_TOOLS = [EXIT_TOOL, WRITE_PLAN_TOOL];
+const CONTROL_TOOLS = [EXIT_TOOL, CANCEL_TOOL, WRITE_PLAN_TOOL];
 
 export interface PlanRuntime {
 	/** Whether plan mode is currently on. */

package/extensions/plan/split.ts

@@ -0,0 +1,87 @@
+/**
+ * The split at approval: the switch that enables it, the roster card, and the
+ * `## Team` section it writes.
+ *
+ * Plan mode keeps one job — the plan document and its approval gate — and this
+ * module is the part of that gate that concerns a team: whether the feature is on,
+ * what the user is told to run in the sessions this package cannot start, and the
+ * write that makes the team real. Everything mechanical about the split itself
+ * (which tables are legal, which paths collide) is `lib/plans/split.ts`, because
+ * the bus reads the same section.
+ */
+
+import { sanitizeLine, shortenPath } from "../../lib/format.ts";
+import { splitEnabled } from "../../lib/plans/setting.ts";
+import { checkSplit, mergeOrder } from "../../lib/plans/split.ts";
+import type { PlanTeam, PlanUnit } from "../../lib/plans/team.ts";
+
+export { SPLIT_OFF_NOTE, SPLIT_SETTING_ID, SPLIT_SETTING_LABEL, splitEnabled } from "../../lib/plans/setting.ts";
+
+/** What approval decides about the units a model proposed. */
+export type SplitDecision =
+	| { kind: "none" }
+	| { kind: "off" }
+	| { kind: "refused"; reason: string }
+	| { kind: "serial" }
+	| { kind: "team"; team: PlanTeam; verdict: "pair" | "team" };
+
+/**
+ * Decide what to do with the `units` an approval carried.
+ *
+ * The switch is checked first: with it off the units are ignored entirely rather
+ * than validated, so a user who never enabled the feature cannot be blocked by a
+ * rule about it.
+ */
+export function decideSplit(
+	cwd: string,
+	root: string | undefined,
+	units: readonly PlanUnit[] | undefined,
+): SplitDecision {
+	if (units === undefined || units.length === 0) return { kind: "none" };
+	if (!splitEnabled(cwd, root)) return { kind: "off" };
+	const check = checkSplit(units);
+	if (!check.ok) return { kind: "refused", reason: check.reason };
+	if (check.verdict === "serial") return { kind: "serial" };
+	return { kind: "team", team: { lead: check.lead, units: check.units }, verdict: check.verdict };
+}
+
+/**
+ * The roster card: what the user runs, in which session, and in what order.
+ *
+ * A lead cannot start, name, or prompt a peer session, so the card is the whole of
+ * what step 3 can do — and its first line says so, because the rest of the flow
+ * depends on the user believing it.
+ */
+export function rosterCard(team: PlanTeam, planPath: string, sessionLabel?: string): string {
+	const lead = team.units.find((unit) => unit.lead)?.name ?? team.lead;
+	const owners = team.units.filter((unit) => !unit.lead);
+	const rows = owners.map((unit) => {
+		const join = `session({action:"join", team:"${teamName(planPath)}", unit:"${unit.name}"})`;
+		return `  ${unit.name}: enter_worktree ${unit.name} · /sessions name ${unit.name} · /sessions watch wake\n    ${join}`;
+	});
+	const order = mergeOrderLine(team);
+	// The lead's own label is the one line of the card it cannot get itself until
+	// after this card is printed, so the card either names it or says how to set it.
+	const name = sessionLabel?.trim();
+	const label = name
+		? `  your label: ${sanitizeLine(name)} — owners send their report there`
+		: `  your label: none — name this session: session({action:"name", label:"${lead}"})`;
+	return [
+		`Split: ${team.units.length} units · ${shortenPath(planPath)}`,
+		"  You start and switch every session; nothing here can.",
+		...rows,
+		`  ${order} · your unit: ${lead}`,
+		label,
+	].join("\n");
+}
+
+/** The team's name is the plan file's stem, so two plans never share one. */
+export function teamName(planPath: string): string {
+	const name = planPath.split(/[\\/]/).pop() ?? planPath;
+	return name.replace(/\.md$/i, "");
+}
+
+/** Merge order in one line, from the dependency graph the validation accepted. */
+export function mergeOrderLine(team: PlanTeam): string {
+	return `merge order: ${mergeOrder(team.units).join(" → ")}`;
+}