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

package/extensions/plan/steps.ts

@@ -10,73 +10,111 @@
  * the digest is computed over.
  *
  * Only top-level list items become steps: nested sub-bullets are notes, and the
- * shallowest list level is treated as the plan. When the plan has a `Steps`
- * section (the canonical outline's heading), only that section's list items are
- * steps, so prose bullets elsewhere never seed the todo list or consume the
- * step cap. List items inside fenced code blocks are ignored. A `- [ ]` / `- [x]`
+ * shallowest list level is treated as the plan. An indented, marker-less line
+ * continues the item above it, so a wrapped step keeps its full text. When the
+ * plan has a `Steps` section (the canonical outline's heading), only that
+ * section's list items are steps, so prose bullets elsewhere never seed the todo
+ * list or consume the step cap. List items inside fenced code blocks are ignored. A `- [ ]` / `- [x]`
  * checkbox or a `[DONE:n]` marker sets the status.
  */
 
+import {
+	extractSections as extractPlanSections,
+	FENCE,
+	HEADING,
+	normalizeHeadingText,
+} from "../../lib/plans/sections.ts";
+
+/**
+ * The section machinery is `lib/plans/sections.ts`, because the split writes
+ * `## Team` with the same fence-aware scan this module navigates with. These
+ * re-exports keep the plan extension's public surface one import.
+ */
+export {
+	extractSections as extractPlanSections,
+	FENCE,
+	HEADING,
+	normalizeHeadingText,
+	replaceSection,
+} from "../../lib/plans/sections.ts";
+export type { PlanSection } from "../../lib/plans/sections.ts";
+
 /** Most steps seeded from one plan. */
 export const MAX_STEPS = 50;
 /** Longest seeded step text; longer lines are elided. */
 export const MAX_STEP_LENGTH = 200;
 
 /**
- * The outline a plan is guided to follow. Guidance only: `write_plan` never
- * rejects or rewrites a plan that omits a section.
+ * The outline a plan is guided to follow: one job per section, and every example
+ * is the shape wanted rather than a description of it. `Visual` is the one
+ * section that carries the end state — the same surface before and after when the
+ * change alters one that already exists, one frame when it is new — in a fence
+ * that stays untagged unless every line is code, so the reviewer sees the result
+ * before the steps that build it. Guidance only: `write_plan` never rejects or
+ * rewrites a plan that omits a section, and a change with no visible surface drops
+ * `Visual`.
  */
 export const PLAN_OUTLINE = [
 	"# <Title>",
 	"",
 	"## Goal",
-	"What this change achieves, and what it deliberately does not.",
+	"One sentence: the outcome this change delivers, and what it deliberately does not do.",
 	"",
 	"## Context",
-	"The relevant code, constraints, and prior art.",
+	"- `src/load.ts:42` reads the config once at startup; that is the only caller.",
+	"- The file is user-editable, so a bad key must name the file and line.",
 	"",
 	"## Approach",
-	"The chosen approach and why; alternatives considered.",
+	"- Parse into a typed record in `parseConfig`; `load()` keeps the file read.",
+	"- Rejected: validating inside `load()`, because the test would need a filesystem.",
+	"",
+	"## Visual",
+	"A bad key at startup, before and after:",
+	"```",
+	"$ bun start",
+	'config.json:12: ignoring unknown key "timeout_ms"',
+	"```",
+	"",
+	"```",
+	"$ bun start",
+	'config.json:12: unknown key "timeout_ms" — did you mean "timeoutMs"?',
+	"```",
 	"",
 	"## Steps",
 	"- [ ] Add `parseConfig` in `src/config.ts`, with a test for a missing key",
-	"- [ ] Wire it into `load()` and document the failure in the README",
+	"  - `load()` is the only caller today; it keeps the file read.",
+	"- [ ] Report a bad key with its file and line, and note the rule in the README",
 	"",
 	"## Risks",
-	"What could go wrong and how it is mitigated.",
+	"- A missing key now fails at startup rather than on first use: name that in the README.",
+	"- Mitigated by the test in the first step.",
 	"",
 	"## Verification",
-	"How to prove it works: commands and checks.",
+	"```bash",
+	"bun test src/config.test.ts",
+	"bun run check",
+	"```",
 ].join("\n");
 
 /** The outline's section titles, in order, for documentation and tests. */
-export const PLAN_SECTIONS = ["Goal", "Context", "Approach", "Steps", "Risks", "Verification"] as const;
+export const PLAN_SECTIONS = ["Goal", "Context", "Approach", "Visual", "Steps", "Risks", "Verification"] as const;
 
 export interface PlanStep {
 	content: string;
 	status: "pending" | "completed";
 }
 
-/** A heading-delimited chunk of the plan, for the review screen's navigation. */
-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 top-level list item located in the source. */
 interface PlanListItem {
-	/** Zero-based source line index. */
+	/** Zero-based source line index of the item's first line. */
 	line: number;
 	indent: number;
 	/** The list marker with its trailing whitespace, e.g. `1. ` or `- `. */
 	lead: string;
-	/** Item text after the marker, right-trimmed (an optional checkbox included). */
+	/**
+	 * Item text after the marker on its first line; indented continuation lines
+	 * are folded into {@link step}, so a checkbox edit rewrites only this line.
+	 */
 	raw: string;
 	step: PlanStep;
 }
@@ -84,39 +122,10 @@ interface PlanListItem {
 /** A top-level numbered or bulleted list item, capturing its parts. */
 const LIST_ITEM = /^([ \t]*)((?:\d+[.)]|[-*+])\s+)(.*\S)\s*$/;
 const CHECKBOX = /^\[([ xX])\]\s*(.*)$/;
-/**
- * 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 `blocks.ts`, 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
- * `blocks.ts`: 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,})/;
 const DONE_MARKER = /\[DONE:\d+\]/gi;
 
-/**
- * A heading or step label as the review surfaces compare it: inline emphasis and
- * code removed, whitespace collapsed. Exported so `blocks.ts` labels an outline
- * entry the same way `extractPlanSections` 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();
-}
-
-/** Strip inline markdown emphasis and code, then collapse to one clean line. */
-function plainText(text: string): string {
+/** A label with its inline markers and any done marker removed. */
+function cleanLabel(text: string): string {
 	return normalizeHeadingText(text.replace(DONE_MARKER, ""));
 }
 
@@ -132,7 +141,12 @@ function parseStep(raw: string): PlanStep {
 	}
 	if (/\[DONE:\d+\]/i.test(text)) done = true;
 
-	return { content: plainText(text), status: done ? "completed" : "pending" };
+	return { content: cleanLabel(text), status: done ? "completed" : "pending" };
+}
+
+/** Leading whitespace width of a line, for continuation indent checks. */
+function indentOf(line: string): number {
+	return line.length - line.trimStart().length;
 }
 
 /** Every top-level list item, in order, before de-duplication and capping. */
@@ -140,22 +154,57 @@ function scanListItems(plan: string): PlanListItem[] {
 	const items: PlanListItem[] = [];
 	// Fences hide example lists (`- name: foo` in a YAML block) from extraction.
 	let fence: string | undefined;
+	// The item still collecting indented continuation lines, and those lines.
+	let current: { item: PlanListItem; continuation: string[] } | undefined;
+
+	/** Fold the collected continuation into the item, then close it. */
+	const finish = (): void => {
+		if (current === undefined) return;
+		if (current.continuation.length > 0) {
+			current.item.step = parseStep(`${current.item.raw} ${current.continuation.join(" ")}`);
+		}
+		current = undefined;
+	};
 
 	plan.split("\n").forEach((line, index) => {
 		const fenceMatch = line.match(FENCE);
 		if (fenceMatch) {
+			finish();
 			if (fence === undefined) fence = fenceMatch[1][0];
 			else if (fence === fenceMatch[1][0]) fence = undefined;
 			return;
 		}
 		if (fence !== undefined) return;
 
+		if (line.trim() === "") {
+			finish();
+			return;
+		}
+
 		const match = line.match(LIST_ITEM);
-		if (!match) return;
-		const step = parseStep(match[3]);
-		if (!step.content) return;
-		items.push({ line: index, indent: match[1].length, lead: match[2], raw: match[3], step });
+		if (match) {
+			finish();
+			const step = parseStep(match[3]);
+			if (!step.content) return;
+			const item: PlanListItem = { line: index, indent: match[1].length, lead: match[2], raw: match[3], step };
+			items.push(item);
+			current = { item, continuation: [] };
+			return;
+		}
+
+		// A deeper, marker-less line continues the step's paragraph; a heading,
+		// a shallow line, or a blank line ends it. `raw` stays the first line so
+		// `setStepStatuses` edits the checkbox without touching these lines.
+		if (current !== undefined && indentOf(line) > current.item.indent && !HEADING.test(line)) {
+			const text = line.trim();
+			if (text) current.continuation.push(text);
+			return;
+		}
+
+		finish();
 	});
+
+	finish();
 	return items;
 }
 
@@ -183,7 +232,7 @@ function stepsSection(plan: string): { start: number; end: number } | undefined
 		if (!heading) continue;
 		const depth = heading[1].length;
 		if (start < 0) {
-			if (plainText(heading[2]).toLowerCase() !== "steps") continue;
+			if (normalizeHeadingText(heading[2]).toLowerCase() !== "steps") continue;
 			start = index;
 			level = depth;
 			continue;
@@ -233,11 +282,12 @@ const LIST_PREFIX = /^\s*(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s*)?/;
  * The plan's `Verification` section as one trailing checklist item, or
  * `undefined` when the plan has none.
  *
- * The section is prose ("commands and checks"), and a todo item is one line, so
- * the lines are stripped of list markers and inline emphasis and joined with
- * `; `, prefixed with `Verify:` and elided like a long step. The item is
- * deliberately *not* a plan step: it is not in the `Steps` section, so it must
- * not count against the step cap or appear in `set_plan_steps` numbering.
+ * The section is prose ("commands and checks") or a fenced block of them, and a
+ * todo item is one line, so the fence lines are dropped, the rest is stripped of
+ * list markers and inline emphasis, and the lines are joined with `; `, prefixed
+ * with `Verify:` and elided like a long step. The item is deliberately *not* a
+ * plan step: it is not in the `Steps` section, so it must not count against the
+ * step cap or appear in `set_plan_steps` numbering.
  *
  * A plan with no `Steps` heading feeds its shallowest list as steps (the older
  * rule), so that list already covers the verification bullets; appending a
@@ -252,7 +302,10 @@ export function verificationItem(plan: string): PlanStep | undefined {
 	const items = section.text
 		.split("\n")
 		.slice(1)
-		.map((line) => plainText(line.replace(LIST_PREFIX, "")))
+		// A fenced block is how the outline asks for commands; its fence lines are
+		// punctuation, not a check, so only the commands inside it are carried.
+		.filter((line) => !FENCE.test(line))
+		.map((line) => cleanLabel(line.replace(LIST_PREFIX, "")))
 		.filter(Boolean);
 	if (items.length === 0) return undefined;
 	return { content: elide(`Verify: ${items.join("; ")}`), status: "pending" };
@@ -332,43 +385,6 @@ export function setStepStatuses(plan: string, updates: readonly StepEdit[]): str
 	return lines.join("\n");
 }
 
-/**
- * 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 extractPlanSections(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: plainText(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;
-}
-
 /**
  * The plan's own objective: the first paragraph of its `## Goal` section, with
  * inline markdown and a leading list marker removed.

package/extensions/plan/tools/cancel.ts

@@ -0,0 +1,79 @@
+/**
+ * The `cancel_plan_mode` tool registration.
+ *
+ * This is the escape hatch that does not need a plan file or a review dialog:
+ * when the user asks to leave planning, the model can restore write access
+ * without approving anything. The plan store is untouched; a later `/plan` can
+ * still review the saved artifact.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { reuseText, toolDetails } from "../../../lib/tui/chrome.ts";
+import { paint } from "../../../lib/tui/tokens.ts";
+import { callLine, detailsOrLine } from "../../../lib/tui/tool.ts";
+import { failedResult } from "../../../lib/tool-result.ts";
+import { CANCEL_TOOL, type PlanRuntime } from "../runtime.ts";
+import type { CancelPlanModeDetails } from "../types.ts";
+
+const CANCELLED_TEXT =
+	"Plan mode is off and write access is restored. The plan was not approved; no todo items or goal were recorded. " +
+	"Any saved plan file remains for a later review.";
+
+export function registerCancelTool(pi: ExtensionAPI, runtime: PlanRuntime): void {
+	pi.registerTool({
+		name: CANCEL_TOOL,
+		label: "Cancel plan mode",
+		description:
+			"Leave plan mode without approving a plan. Restores write access; no todo items or goal are recorded. " +
+			"Use when the user asks to exit, cancel, or abandon planning.",
+		promptSnippet: "Leave plan mode without approving the plan.",
+		promptGuidelines: [
+			"Call cancel_plan_mode when the user asks to leave or abandon planning without approving a plan.",
+		],
+		parameters: Type.Object({}),
+		defaultActive: false,
+		executionMode: "sequential",
+		// The mode change touches no files; like enter_plan_mode, it needs no
+		// destructive annotation.
+		annotations: { readOnlyHint: true, openWorldHint: false },
+
+		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+			if (!runtime.isEnabled()) {
+				return failedResult("Not in plan mode; there is nothing to cancel.", {
+					cancelled: false,
+				} satisfies CancelPlanModeDetails);
+			}
+			runtime.disable(ctx);
+			ctx.ui.notify("Plan mode off — full access restored. The plan was not approved.", "info");
+			return {
+				content: [{ type: "text", text: CANCELLED_TEXT }],
+				details: { cancelled: true } satisfies CancelPlanModeDetails,
+			};
+		},
+
+		renderCall(_args, theme, context) {
+			return callLine(theme, context?.lastComponent, CANCEL_TOOL, "left plan mode");
+		},
+
+		renderResult(result, options, theme, context) {
+			const text = reuseText(context?.lastComponent);
+			const outcome = detailsOrLine(
+				theme,
+				result,
+				options.expanded,
+				toolDetails<CancelPlanModeDetails>(result.details),
+			);
+			if ("line" in outcome) {
+				text.setText(outcome.line);
+				return text;
+			}
+			text.setText(
+				outcome.details.cancelled
+					? paint(theme, "warn", "Plan mode off — plan not approved")
+					: paint(theme, "meta", "Not in plan mode"),
+			);
+			return text;
+		},
+	});
+}

package/extensions/plan/tools/enter.ts

@@ -11,7 +11,9 @@ import { reuseText, toolDetails } from "../../../lib/tui/chrome.ts";
 import { GLYPHS } from "../../../lib/tui/glyphs.ts";
 import { paint } from "../../../lib/tui/tokens.ts";
 import { callLine, detailsOrLine } from "../../../lib/tui/tool.ts";
-import { PLAN_CONSENT, READ_ONLY_SUMMARY } from "../../../lib/plan-entry.ts";
+import { failedResult } from "../../../lib/tool-result.ts";
+import { isRemoteTurn, remoteLanguage } from "../../../lib/interaction.ts";
+import { PLAN_CONSENT, PLAN_CONSENT_SHORT, PLAN_CONSENT_SHORT_ZH, READ_ONLY_SUMMARY } from "../../../lib/plan-entry.ts";
 import { ENTER_TOOL, type PlanRuntime } from "../runtime.ts";
 import type { EnterPlanModeDetails } from "../types.ts";
 
@@ -45,19 +47,18 @@ export function registerEnterTool(pi: ExtensionAPI, runtime: PlanRuntime): void
 				};
 			}
 			if (!ctx.hasUI) {
-				return {
-					content: [
-						{
-							type: "text",
-							text: "No interactive UI is available to confirm entering plan mode. Ask the user whether they want a plan.",
-						},
-					],
-					details: { entered: false, unavailable: true } satisfies EnterPlanModeDetails,
-					isError: true,
-				};
+				return failedResult(
+					"No interactive UI is available to confirm entering plan mode. Ask the user whether they want a plan.",
+					{ entered: false, unavailable: true } satisfies EnterPlanModeDetails,
+				);
 			}
 
-			const approved = await ctx.ui.confirm("Enter plan mode?", PLAN_CONSENT);
+			const consent = isRemoteTurn(ctx)
+				? remoteLanguage(ctx) === "zh"
+					? PLAN_CONSENT_SHORT_ZH
+					: PLAN_CONSENT_SHORT
+				: PLAN_CONSENT;
+			const approved = await ctx.ui.confirm("Enter plan mode?", consent);
 			if (!approved) {
 				return {
 					content: [{ type: "text", text: "Stayed in normal mode. Proceed, or ask the user how to continue." }],
@@ -65,6 +66,10 @@ export function registerEnterTool(pi: ExtensionAPI, runtime: PlanRuntime): void
 				};
 			}
 			runtime.enable(ctx);
+			if (isRemoteTurn(ctx)) {
+				// The peer UI has no footer chip; say the mode and its exit in the chat.
+				ctx.ui.notify("Plan mode on — write access is off. Say “exit plan mode” to leave without approving.", "info");
+			}
 			return {
 				content: [{ type: "text", text: ENTERED_TEXT }],
 				details: { entered: true } satisfies EnterPlanModeDetails,