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

package/extensions/plan/tools/exit.ts

@@ -18,6 +18,8 @@ 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, moreHint } from "../../../lib/tui/tool.ts";
+import { failedResult } from "../../../lib/tool-result.ts";
+import { loadConfig } from "../config.ts";
 import { feedbackSummary } from "../feedback.ts";
 import { mergeSummary, overCap, preview, verificationNote } from "../format.ts";
 import { sanitizePlanText } from "../plan-text.ts";
@@ -51,7 +53,8 @@ interface GoalOutcome {
  * Finalise the session goal from the approved plan.
  *
  * A `planning` goal needs no dialog — approving the plan *is* the decision — and a
- * session with no goal at all gets one confirm. A final goal (`active` or
+ * session with no goal at all gets one confirm, unless `plan.goalPrompt` is off,
+ * which records the objective without asking. A final goal (`active` or
  * `achieved`) is the user's own: approving ordinary work never rewrites it.
  * Recording runs through the goal tool, so validation and the widget stay goal's,
  * and no model turn is spent.
@@ -62,8 +65,10 @@ async function finalizeGoal(ctx: ExtensionToolContext, plan: StoredPlan): Promis
 	if (current !== null && current.status !== "planning") return { objective };
 	if (current === null) {
 		if (!ctx.hasUI) return { objective };
-		const approved = await ctx.ui.confirm("Record this plan as the session goal?", objective);
-		if (!approved) return { objective };
+		if (loadConfig(ctx.cwd).goalPrompt) {
+			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, status: "active" });
 	const action = current === null ? "recorded" : "promoted";
@@ -99,65 +104,47 @@ export function registerExitTool(pi: ExtensionAPI, runtime: PlanRuntime, web: Pl
 			const planPath = (params as ExitPlanModeArgs).plan_path.trim();
 
 			if (!runtime.isEnabled()) {
-				return {
-					content: [{ type: "text", text: "Not in plan mode; there is no plan to approve." }],
-					details: { approved: false, plan: "", planPath } satisfies ExitPlanModeDetails,
-					isError: true,
-				};
+				return failedResult("Not in plan mode; there is no plan to approve.", {
+					approved: false,
+					plan: "",
+					planPath,
+				} satisfies ExitPlanModeDetails);
 			}
 
 			const file = await runtime.plans.read(ctx.cwd, planPath);
 			if (!file) {
-				return {
-					content: [
-						{
-							type: "text",
-							text: `No plan file at "${planPath}". Save the plan with write_plan first, then pass the returned path.`,
-						},
-					],
-					details: { approved: false, plan: "", planPath } satisfies ExitPlanModeDetails,
-					isError: true,
-				};
+				return failedResult(
+					`No plan file at "${planPath}". Save the plan with write_plan first, then pass the returned path.`,
+					{ approved: false, plan: "", planPath } satisfies ExitPlanModeDetails,
+				);
 			}
 
 			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: {
+				return failedResult(
+					`${overCap(total)} It was not presented for approval; call write_plan with plan_path to group the steps, then exit_plan_mode again.`,
+					{
 						approved: false,
 						plan: file.content,
 						planPath: file.path,
 						relativePath: file.relativePath,
 					} satisfies ExitPlanModeDetails,
-					isError: true,
-				};
+				);
 			}
 
 			if (!ctx.hasUI) {
-				return {
-					content: [
-						{
-							type: "text",
-							text: `No interactive UI is available to approve the plan. It is saved at ${file.relativePath}; present it and ask the user to approve it in their reply.`,
-						},
-					],
-					details: {
+				return failedResult(
+					`No interactive UI is available to approve the plan. It is saved at ${file.relativePath}; present it and ask the user to approve it in their reply.`,
+					{
 						approved: false,
 						plan: file.content,
 						planPath: file.path,
 						relativePath: file.relativePath,
 						unavailable: true,
 					} satisfies ExitPlanModeDetails,
-					isError: true,
-				};
+				);
 			}
 
 			// One decision, however the session is attached; `review.ts` owns the loop,
@@ -208,6 +195,28 @@ export function registerExitTool(pi: ExtensionAPI, runtime: PlanRuntime, web: Pl
 					} satisfies ExitPlanModeDetails,
 				};
 			}
+			if (decision.action === "cancel") {
+				runtime.disable(ctx);
+				const shown = decision.plan.relativePath;
+				ctx.ui.notify("Plan mode off — full access restored. The plan was not approved.", "info");
+				return {
+					content: [
+						{
+							type: "text",
+							text:
+								"Plan mode is off and write access is restored. The plan was not approved and no steps were recorded. " +
+								`The plan file ${shown} remains if the user wants to review it later.`,
+						},
+					],
+					details: {
+						approved: false,
+						cancelled: true,
+						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, decision.plan.content);
@@ -269,11 +278,13 @@ export function registerExitTool(pi: ExtensionAPI, runtime: PlanRuntime, web: Pl
 			const details = outcome.details;
 			const heading = details.unavailable
 				? paint(theme, "warn", "No UI to approve the plan")
-				: details.approved
-					? paint(theme, "ok", `${GLYPHS.check} Plan approved`)
-					: details.refined
-						? paint(theme, "accent", "Refining the plan")
-						: paint(theme, "warn", "Plan not approved");
+				: details.cancelled
+					? paint(theme, "warn", "Plan mode off — plan not approved")
+					: details.approved
+						? paint(theme, "ok", `${GLYPHS.check} Plan approved`)
+						: details.refined
+							? paint(theme, "accent", "Refining the plan")
+							: paint(theme, "warn", "Plan not approved");
 			const extra =
 				details.refined && details.refinement
 					? `\n${paint(theme, "meta", `↳ ${sanitizePlanText(details.refinement)}`)}`

package/extensions/plan/tools/steps.ts

@@ -13,6 +13,7 @@ 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 { failedResult, textResult } from "../../../lib/tool-result.ts";
 import { describeUpdates, stepLabel } from "../format.ts";
 import { SET_PLAN_STEPS_TOOL, type PlanRuntime } from "../runtime.ts";
 import { extractPlanSteps } from "../steps.ts";
@@ -66,39 +67,26 @@ export function registerSetPlanStepsTool(pi: ExtensionAPI, runtime: PlanRuntime)
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			const args = params as SetPlanStepsArgs;
 			if (runtime.isEnabled()) {
-				return {
-					content: [{ type: "text", text: "Not while planning; refine the plan with write_plan instead." }],
-					details: undefined,
-					isError: true,
-				};
+				return failedResult("Not while planning; refine the plan with write_plan instead.", undefined);
 			}
 			try {
 				const plan = await runtime.plans.setSteps(ctx.cwd, args.plan_path, args.updates);
 				const steps = extractPlanSteps(plan.content);
 				const done = steps.filter((step) => step.status === "completed").length;
 				const todoNote = await mirrorTodos(ctx, args.updates);
-				return {
-					content: [
-						{
-							type: "text",
-							text: `${describeUpdates(args.updates)} (${done}/${steps.length} done) in ${plan.relativePath}${todoNote}.`,
-						},
-					],
-					details: {
+				return textResult(
+					`${describeUpdates(args.updates)} (${done}/${steps.length} done) in ${plan.relativePath}${todoNote}.`,
+					{
 						path: plan.path,
 						relativePath: plan.relativePath,
 						updates: args.updates,
 						done,
 						total: steps.length,
 					} satisfies SetPlanStepsDetails,
-				};
+				);
 			} catch (error) {
 				const message = error instanceof Error ? error.message : String(error);
-				return {
-					content: [{ type: "text", text: `Could not update the plan: ${message}` }],
-					details: undefined,
-					isError: true,
-				};
+				return failedResult(`Could not update the plan: ${message}`, undefined);
 			}
 		},
 

package/extensions/plan/tools/write.ts

@@ -12,6 +12,7 @@ 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 { failedResult, textResult } from "../../../lib/tool-result.ts";
 import { overCap, stepElisionNote } from "../format.ts";
 import { WRITE_PLAN_TOOL, type PlanRuntime } from "../runtime.ts";
 import { MAX_STEPS, PLAN_OUTLINE, planStepSummary } from "../steps.ts";
@@ -42,11 +43,22 @@ export function registerWriteTool(pi: ExtensionAPI, runtime: PlanRuntime): void
 			"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` +
+			"Each section has one job: lead it with its outcome, keep a prose section to a few bullets or two or three " +
+			"sentences, give each step one verifiable outcome with the detail in a nested note, and put the sketch, files, " +
+			"and commands in inline code or a fence rather than pasted prose. " +
+			"When the change alters a surface that already exists, Visual shows it before and after in one fence each; " +
+			"tag a fence only when every line in it is code. " +
+			"The outline is a guide, not a form: drop Context, Approach, Visual, or Risks when there is nothing to say. " +
+			"Keep Steps and Verification — the steps are read from that section (without it, the shallowest list " +
+			"anywhere becomes the steps), and Verification becomes the last todo item. " +
+			"In Steps, each top-level bullet is one outcome in the order you will do them, and deeper bullets are notes. " +
 			"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.",
+			"When refining with plan_path, keep every section heading as it was: the review marks changed sections by heading, " +
+				"so a rename reads as an edit.",
 		],
 		parameters: WritePlanParams,
 		defaultActive: false,
@@ -57,27 +69,17 @@ export function registerWriteTool(pi: ExtensionAPI, runtime: PlanRuntime): void
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			if (!runtime.isEnabled()) {
-				return {
-					content: [{ type: "text", text: "Not in plan mode; call enter_plan_mode first." }],
-					details: undefined,
-					isError: true,
-				};
+				return failedResult("Not in plan mode; call enter_plan_mode first.", undefined);
 			}
 			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,
-				};
+				return failedResult(
+					`${overCap(summary.total)} Nothing was written; group the steps (one outcome each, sub-bullets for detail) and call write_plan again.`,
+					undefined,
+				);
 			}
 			try {
 				const file = await runtime.plans.write(ctx.cwd, {
@@ -86,22 +88,13 @@ export function registerWriteTool(pi: ExtensionAPI, runtime: PlanRuntime): void
 					planPath: args.plan_path,
 				});
 				runtime.setLastPlan(ctx, file.path);
-				return {
-					content: [
-						{
-							type: "text",
-							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,
-				};
+				return textResult(
+					`Wrote the plan to ${file.relativePath}. Call exit_plan_mode with plan_path: ${file.path}${stepElisionNote(summary.elided)}`,
+					{ path: file.path, relativePath: file.relativePath, bytes: file.bytes } satisfies WritePlanDetails,
+				);
 			} catch (error) {
 				const message = error instanceof Error ? error.message : String(error);
-				return {
-					content: [{ type: "text", text: `Could not write the plan: ${message}` }],
-					details: undefined,
-					isError: true,
-				};
+				return failedResult(`Could not write the plan: ${message}`, undefined);
 			}
 		},
 

package/extensions/plan/tools.ts

@@ -3,8 +3,9 @@
  *
  * `enter_plan_mode` lets the model ask to plan before touching code; it needs
  * user confirmation. `write_plan` saves the plan artifact under `.pi/plans` and
- * returns its path. `exit_plan_mode` reads that file back, presents it for
- * approval (a scrollable review screen in the TUI, a select dialog elsewhere),
+ * returns its path. `cancel_plan_mode` leaves planning without approving, so a
+ * phone user is never trapped in read-only mode. `exit_plan_mode` reads that file
+ * back, presents it for approval (a scrollable review screen in the TUI, a select dialog elsewhere),
  * and on approval seeds the `todo` tool with the plan's steps (through
  * `ctx.executeTool`, so the todo widget and validation run normally).
  * `set_plan_steps` then keeps the plan current: after approval the model ticks
@@ -22,6 +23,7 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { PlanRuntime } from "./runtime.ts";
+import { registerCancelTool } from "./tools/cancel.ts";
 import { registerEnterTool } from "./tools/enter.ts";
 import { registerExitTool } from "./tools/exit.ts";
 import { registerSetPlanStepsTool } from "./tools/steps.ts";
@@ -34,6 +36,7 @@ export function registerTools(
 	web: PlanWebReview = createPlanWebReview(runtime.plans),
 ): void {
 	registerEnterTool(pi, runtime);
+	registerCancelTool(pi, runtime);
 	registerWriteTool(pi, runtime);
 	registerExitTool(pi, runtime, web);
 	registerSetPlanStepsTool(pi, runtime);

package/extensions/plan/tui.ts

@@ -37,7 +37,7 @@ import {
 import { isCloseKey } from "../../lib/tui/cursor.ts";
 import { gaugeBar } from "../../lib/tui/gauge.ts";
 import { GLYPHS } from "../../lib/tui/glyphs.ts";
-import { titleRule } from "../../lib/tui/rules.ts";
+import { plainRule, titleRule } from "../../lib/tui/rules.ts";
 import { emptyState, checkbox } from "../../lib/tui/rows.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import { planTitle, type StoredPlan } from "./plans.ts";
@@ -45,7 +45,7 @@ import { changedSections, sanitizePlanText, type SectionDigest } from "./plan-te
 import { extractPlanSections } from "./steps.ts";
 
 /** What the user chose from the read/review screen. */
-export type PlanViewAction = "approve" | "refine" | "keep" | "browser";
+export type PlanViewAction = "approve" | "refine" | "keep" | "browser" | "cancel";
 
 /** A plan section's rendered start line, for navigation and the current-section label. */
 interface SectionOffset {
@@ -87,7 +87,7 @@ export interface PlanViewOptions {
 
 /** Rows the screen shows when the terminal height is unknown. */
 const DEFAULT_ROWS = 20;
-/** Header, blanks, footer, and trailing rows around a non-empty plan. */
+/** Header, blanks, footer, and closing rule around a non-empty plan. */
 const CHROME_ROWS = 5;
 /** Narrowest width where Markdown's 2-column padding still fits the body. */
 const MIN_PADDED_WIDTH = 6;
@@ -97,13 +97,14 @@ const BODY_PADDING = 2;
 const GAUGE_SEGMENTS = 10;
 /** Footer hints shared by the review and the inline editor's primary actions. */
 const PRIMARY_HINTS: ScreenHint[] = [
-	"Esc keep planning",
-	{ text: "a approve & run", color: "success" },
+	"Esc keep plan",
+	{ text: "a approve", color: "success" },
 	{ text: "r refine", color: "accent" },
 	{ text: "w browser", color: "accent" },
+	{ text: "x exit plan", color: "warning" },
 ];
 /** Scroll keys appended to the review footer while the plan overflows. */
-const SCROLL_HINTS: ScreenHint[] = ["↑/↓ or k/j scroll", "space/b page", "g/G ends"];
+const SCROLL_HINTS: ScreenHint[] = ["j/k scroll", "space page", "g/G ends"];
 /** Section-jump hint, shown when the plan has more than one heading section. */
 const SECTION_HINTS: ScreenHint[] = ["n/p section"];
 
@@ -332,6 +333,7 @@ export class PlanViewComponent implements Component {
 		else if (data === "a") this.options.onClose("approve");
 		else if (data === "r") this.startRefine();
 		else if (data === "w") this.options.onClose("browser");
+		else if (data === "x") this.options.onClose("cancel");
 	}
 
 	/** Wheel scrolling in fullscreen; regular mode leaves the wheel to the terminal. */
@@ -403,7 +405,7 @@ export class PlanViewComponent implements Component {
 				this.maxOffset > 0 ? [...PRIMARY_HINTS, ...SCROLL_HINTS, ...sectionHints] : PRIMARY_HINTS;
 			lines.push(screenHint(theme, w, hints));
 		}
-		lines.push("");
+		lines.push(plainRule(theme, w));
 		return lines;
 	}
 }

package/extensions/plan/types.ts

@@ -74,6 +74,14 @@ export interface ExitPlanModeDetails {
 	refinement?: string;
 	/** Comments the review carried when it approved or requested a refinement. */
 	annotations?: PlanAnnotation[];
+	/** True when the user left plan mode without approving the plan. */
+	cancelled?: boolean;
 	/** True when no interactive UI was available to ask for approval. */
 	unavailable?: boolean;
 }
+
+/** Structured result carried in `cancel_plan_mode`'s `details`. */
+export interface CancelPlanModeDetails {
+	/** True when plan mode was on and has now been turned off. */
+	cancelled: boolean;
+}

package/extensions/plan/web-chrome.ts

@@ -0,0 +1,101 @@
+/**
+ * The review page's chrome: what the page says about itself.
+ *
+ * It is a fragment of the same IIFE `web-client.ts` ships (`WEB_CHROME_JS` is
+ * interpolated into `REVIEW_CLIENT_JS`), kept in its own module so the state
+ * chip, the status line, and the header are read together and away from the
+ * document rendering. It paints only text it was handed.
+ */
+
+export const WEB_CHROME_JS = String.raw`  function setStatus(text, kind) {
+    if (!statusEl) return;
+    statusEl.textContent = text || "";
+    statusEl.title = text || "";
+    statusEl.className = kind ? "bf-status bf-status--" + kind : "bf-status";
+  }
+
+  // The always-visible header chip: connection, comment count, and whether
+  // there are edits the file does not have yet.
+  function updateState() {
+    if (!stateEl) return;
+    var label;
+    var tone = "";
+    if (approved) {
+      label = "Approved";
+      tone = "success";
+    } else if (saved) {
+      label = "Saved";
+      tone = "success";
+    } else if (closed) {
+      // Settled by the user, not by a dropped stream: never flash Offline.
+      label = "Closed";
+    } else if (connected === true) {
+      label = "Connected";
+      tone = "success";
+    } else if (everConnected) {
+      // Only after the stream has opened once: an error before that is a
+      // transient initial connect, so keep showing Connecting rather than Offline.
+      label = "Offline";
+      tone = "danger";
+    } else {
+      label = "Connecting\u2026";
+    }
+    var count = annotations.length;
+    label += " \u00b7 " + count + (count === 1 ? " comment" : " comments");
+    if (dirty && !saved && !approved && !closed) {
+      label += " \u00b7 unsaved";
+      if (!tone) tone = "warn";
+    }
+    stateEl.textContent = label;
+    stateEl.className = "bf-chip bf-chip--accent review-state" + (tone ? " bf-chip--" + tone : "");
+  }
+
+  function renderHeader() {
+    var titleEl = document.getElementById("plan-title");
+    if (titleEl && data.title) {
+      titleEl.textContent = data.title;
+      titleEl.title = data.title;
+    }
+    if (data.title) document.title = "Plan review \u00b7 " + data.title;
+  }
+
+  function updateProgress() {
+    if (!progressEl) return;
+    var doc = document.scrollingElement || document.documentElement;
+    var top = doc ? doc.scrollTop : 0;
+    var height = doc ? doc.scrollHeight : 0;
+    var view = doc ? doc.clientHeight : 0;
+    if (planEl && planEl.scrollHeight > planEl.clientHeight + 4) {
+      top = planEl.scrollTop; height = planEl.scrollHeight; view = planEl.clientHeight;
+    }
+    var max = height - view;
+    var percent = max > 0 ? Math.min(100, Math.max(0, (top / max) * 100)) : 0;
+    progressEl.style.width = percent + "%";
+  }
+
+  function lockActions() {
+    if (approveButton) approveButton.disabled = true;
+    if (saveButton) saveButton.disabled = true;
+    if (cancelButton) cancelButton.disabled = true;
+  }
+
+  // A conflict means the file moved under the page; only a reload can re-anchor.
+  function offerReload() {
+    if (document.getElementById("reload")) return;
+    var controls = document.querySelector(".review-controls");
+    if (!controls) return;
+    var reload = el("button");
+    reload.type = "button";
+    reload.id = "reload";
+    reload.className = "bf-btn bf-btn--primary";
+    reload.textContent = "Reload";
+    reload.addEventListener("click", function () { window.location.reload(); });
+    controls.appendChild(reload);
+  }
+
+  // The stream exists only to notice a closed tab. Once the review is settled it
+  // has no job, and leaving it open retries a dead port until the tab closes.
+  function settleStream() {
+    if (stream && stream.close) { stream.close(); stream = null; }
+  }
+`;