@gavin-hu/my-pi-agent 0.20.0 → 0.22.0

package/extensions/plan/tools.ts

@@ -1,43 +1,201 @@
 /**
- * Model-facing registration for the plan-mode tools.
+ * Model-facing registration for the `plan` tool.
  *
- * `enter_plan_mode` lets the model ask to plan before touching code; it needs
- * user confirmation. `write_plan` saves the plan artifact in the plans directory and
- * 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
- * each step off in place as it finishes it, and the todo item approval seeded
- * from that step is ticked with it. The file is the source of truth: the model
- * executes from it.
+ * One tool with five actions, like `board` and `memory`: `enter` asks the user to
+ * plan before touching code, `write` saves the plan artifact in the plans
+ * directory and returns its path, `exit` reads that file back and presents it for
+ * approval, `steps` keeps an approved plan current, and `cancel` leaves planning
+ * without approving, so a phone user is never trapped in read-only mode.
  *
- * Each registration lives in `tools/`: its schema, execute handler, and
- * transcripts stay together, and the approval-time helpers they share live next
- * to them. This module only composes them, in the order the session sees them.
+ * `exit` presents the plan through `review.ts` (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. After approval the model ticks each step off in place with `steps`, and
+ * the todo item approval seeded from that step is ticked with it. The file is the
+ * source of truth: the model executes from it.
  *
- * Without an interactive UI the approval tools fail with an actionable message
- * instead of deciding for the user.
+ * Each action lives in `tools/`: its execute handler and the block it draws stay
+ * together, and the approval-time helpers they share live next to them. This
+ * module only composes them, in the order the description names them.
+ *
+ * Without an interactive UI the two actions that need one (`enter`, `exit`) fail
+ * with an actionable message instead of deciding for the user.
  */
 
 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";
-import { registerWriteTool } from "./tools/write.ts";
-import { createPlanWebReview, type PlanWebReview } from "./web.ts";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
+import { paint } from "../../lib/tui/tokens.ts";
+import { detailsOrLine, messageText, callLine } from "../../lib/tui/tool.ts";
+import { MAX_STEPS, PLAN_OUTLINE } from "./steps.ts";
+import { PLAN_ACTIONS, PLAN_TOOL, type PlanAction, type PlanRuntime } from "./runtime.ts";
+import { callCancel, executeCancel, textCancel } from "./tools/cancel.ts";
+import { callEnter, executeEnter, textEnter } from "./tools/enter.ts";
+import { callExit, executeExit, textExit } from "./tools/exit.ts";
+import { callSteps, executeSteps, StepUpdateParams, textSteps } from "./tools/steps.ts";
+import { callWrite, executeWrite, textWrite } from "./tools/write.ts";
+import type { PlanDetails } from "./types.ts";
+import { createLazyPlanWebReview, NO_SERVER_DEPS } from "./web-lazy.ts";
+import type { PlanWebReview } from "./web.ts";
+
+const PlanParams = Type.Object({
+	action: StringEnum(PLAN_ACTIONS, {
+		description:
+			"`enter` asks to plan, `write` saves the plan file, `exit` presents it for approval, `steps` ticks its steps, `cancel` leaves without approving.",
+	}),
+	title: Type.Optional(
+		Type.String({
+			description: '`write`: short title for the plan, used as the file-name slug, e.g. "Add rate limiting".',
+		}),
+	),
+	content: Type.Optional(
+		Type.String({
+			description: "`write`: the complete plan as markdown in the documented outline, including every step.",
+		}),
+	),
+	plan_path: Type.Optional(
+		Type.String({
+			description:
+				"`write`: overwrite an existing plan file (one an earlier `write` returned) to refine it instead of creating a new one. " +
+				"`exit`: the file `write` returned, which the user reviews. " +
+				"`steps`: the approved plan file, as `exit` returned it.",
+		}),
+	),
+	updates: Type.Optional(
+		Type.Array(StepUpdateParams, {
+			minItems: 1,
+			description:
+				"`steps`: the steps to set; each entry sets one step's checkbox, and the last entry wins for a duplicate step.",
+		}),
+	),
+});
+
+const DESCRIPTION =
+	"Plan mode and the plan file it is built around, in one tool. `enter` asks the user to enter read-only plan mode; " +
+	"`write` saves the plan you designed as markdown in the plans directory; `exit` presents the saved plan for approval; " +
+	"`steps` ticks its steps off in place; `cancel` leaves plan mode without approving. Each action refuses outside its " +
+	"mode, and every field but `action` says which action reads it.\n\n" +
+	"`write` takes 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; " +
+	"an indented line continues that outcome, and a deeper bullet is a note. " +
+	`A plan with more than ${MAX_STEPS} top-level steps in its Steps section is refused, so approval never drops steps it ` +
+	"cannot track. `write` returns the path to pass to `exit`; plan_path overwrites an existing file when refining.\n\n" +
+	"`steps` sets the checkboxes of the given top-level steps of an approved plan in one write, and their todo items " +
+	"with them. Each step number matches the order the plan was approved in; a step can be marked completed or reopened. " +
+	"Only the checkboxes change; the step text is left as written. The file is rewritten once, and nothing changes when " +
+	"any step is out of range or an entry's expected text no longer matches the file.\n\n" +
+	"`exit` reads the plan file back and presents it with approve, keep, refine, and exit choices; on approval plan mode " +
+	"ends, write access returns, and the plan's steps go into the todo list. The plan file stays the source of truth. " +
+	"`cancel` is the escape hatch that needs no plan file: write access returns and nothing is recorded.";
+
+/** The verb a call names, or undefined for a transcript recorded before the fold. */
+function planActionOf(raw: unknown): PlanAction | undefined {
+	return typeof raw === "string" ? PLAN_ACTIONS.find((action) => action === raw) : undefined;
+}
 
 export function registerTools(
 	pi: ExtensionAPI,
 	runtime: PlanRuntime,
-	web: PlanWebReview = createPlanWebReview(runtime.plans),
+	web: PlanWebReview = createLazyPlanWebReview(runtime.plans, NO_SERVER_DEPS),
 ): void {
-	registerEnterTool(pi, runtime);
-	registerCancelTool(pi, runtime);
-	registerWriteTool(pi, runtime);
-	registerExitTool(pi, runtime, web);
-	registerSetPlanStepsTool(pi, runtime);
+	pi.registerTool<typeof PlanParams, PlanDetails>({
+		name: PLAN_TOOL,
+		label: "Plan",
+		description: DESCRIPTION,
+		promptSnippet: "Enter read-only plan mode, save the plan, present it for approval, tick its steps, or leave it.",
+		promptGuidelines: [
+			"Call plan with action enter before a non-trivial implementation task; skip it for small, obvious changes.",
+			"While plan mode is active, write the full plan with action write, then call action exit with the returned plan_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.",
+			"After a plan is approved, call action steps as you complete steps, passing each step's text as expected so a " +
+				"reordered plan is refused instead of mis-ticked.",
+			"Call action cancel when the user asks to leave or abandon planning without approving a plan.",
+		],
+		parameters: PlanParams,
+		executionMode: "sequential",
+		// One annotation set for five verbs, so it takes the strictest of them: `write`
+		// overwrites a plan file with plan_path. The actions that only change the mode
+		// are exempted by the guard in `index.ts`, which is the only place that can
+		// still tell them apart.
+		annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			switch (params.action) {
+				case "enter":
+					return await executeEnter(runtime, ctx);
+				case "write":
+					return await executeWrite(runtime, params, ctx);
+				case "exit":
+					return await executeExit(pi, runtime, web, params, ctx, signal);
+				case "steps":
+					return await executeSteps(runtime, params, ctx);
+				case "cancel":
+					return await executeCancel(runtime, ctx);
+			}
+		},
+
+		renderCall(args, theme, context) {
+			const last = context?.lastComponent;
+			switch (planActionOf(args.action)) {
+				case "enter":
+					return callEnter(theme, last);
+				case "write":
+					return callWrite(args, theme, last);
+				case "exit":
+					return callExit(args, theme, last);
+				case "steps":
+					return callSteps(args, theme, last);
+				case "cancel":
+					return callCancel(theme, last);
+				case undefined:
+					return callLine(theme, last, PLAN_TOOL, "");
+			}
+		},
+
+		renderResult(result, options, theme, context) {
+			const text = reuseText(context?.lastComponent);
+			const details = toolDetails<PlanDetails>(result.details);
+			const outcome = detailsOrLine(theme, result, options.expanded, details);
+			if ("line" in outcome) {
+				text.setText(outcome.line);
+				return text;
+			}
+			const found = outcome.details;
+			// No `action` means a refusal (which reports only its verb and reason), or a
+			// result recorded before the tool was folded; its own text is what is left.
+			if (!("action" in found)) {
+				text.setText(paint(theme, "toolOutput", messageText(result)));
+				return text;
+			}
+			switch (found.action) {
+				case "enter":
+					text.setText(textEnter(found, theme));
+					break;
+				case "write":
+					text.setText(textWrite(found, theme));
+					break;
+				case "exit":
+					text.setText(textExit(found, options.expanded, theme));
+					break;
+				case "steps":
+					text.setText(textSteps(found, theme));
+					break;
+				case "cancel":
+					text.setText(textCancel(found, theme));
+					break;
+			}
+			return text;
+		},
+	});
 }

package/extensions/plan/tui.ts

@@ -1,7 +1,7 @@
 /**
  * Terminal rendering for the plan review screen.
  *
- * `PlanViewComponent` is the scrollable review screen `exit_plan_mode` opens
+ * `PlanViewComponent` is the scrollable review screen the `exit` action opens
  * for approval. The plan body is rendered by Pi's own `Markdown` component with
  * the active Markdown theme, so headings, lists, code, links, and quotes match
  * the rest of the application; plan-authored control characters are stripped
@@ -100,10 +100,10 @@ const GAUGE_SEGMENTS = 10;
 /** Footer hints shared by the review and the inline editor's primary actions. */
 const PRIMARY_HINTS: ScreenHint[] = [
 	"Esc keep plan",
-	{ text: "a approve", color: "success" },
+	{ text: "a approve", color: "ok" },
 	{ text: "r refine", color: "accent" },
 	{ text: "w browser", color: "accent" },
-	{ text: "x exit plan", color: "warning" },
+	{ text: "x exit plan", color: "warn" },
 ];
 /** Scroll keys appended to the review footer while the plan overflows. */
 const SCROLL_HINTS: ScreenHint[] = ["j/k scroll", "space page", "g/G ends"];
@@ -168,7 +168,7 @@ function scrollRow(
 	return truncateToWidth(`  ${head}`, width);
 }
 
-/** Scrollable plan review screen opened by `exit_plan_mode`. */
+/** Scrollable plan review screen opened by the `exit` action. */
 export class PlanViewComponent implements Component {
 	private offset = 0;
 	private visible = DEFAULT_ROWS;
@@ -407,7 +407,7 @@ export class PlanViewComponent implements Component {
 			lines.push(truncateToWidth(`  ${paint(theme, "meta", "Refine the plan:")}`, w));
 			for (const line of editorLines) lines.push(truncateToWidth(`  ${line}`, w));
 			lines.push("");
-			lines.push(screenHint(theme, w, ["Esc back to plan", { text: "Enter submit", color: "success" }]));
+			lines.push(screenHint(theme, w, ["Esc back to plan", { text: "Enter submit", color: "ok" }]));
 		} else {
 			if (this.maxOffset > 0) lines.push(scrollRow(theme, w, this.offset, end, body.length, sectionLabel));
 			else lines.push("");

package/extensions/plan/types.ts

@@ -4,6 +4,9 @@
 
 import type { PlanAnnotation } from "./feedback.ts";
 import type { SectionDigest } from "./plan-text.ts";
+import type { PlanAction } from "./runtime.ts";
+
+export type { PlanAction };
 import type { StepUpdate } from "./steps.ts";
 
 /**
@@ -65,8 +68,10 @@ export interface SeededStepsEntry {
 	steps: string[];
 }
 
-/** Structured result carried in `enter_plan_mode`'s `details`. */
+/** Structured result carried in the `plan` tool's `details` for `action: "enter"`. */
 export interface EnterPlanModeDetails {
+	/** The verb this result answers, so a renderer reads the result instead of the call. */
+	action: "enter";
 	/** Whether the user agreed to enter plan mode. */
 	entered: boolean;
 	/** True when plan mode was already enabled before this call. */
@@ -75,8 +80,10 @@ export interface EnterPlanModeDetails {
 	unavailable?: boolean;
 }
 
-/** Structured result carried in `write_plan`'s `details`. */
+/** Structured result carried in the `plan` tool's `details` for `action: "write"`. */
 export interface WritePlanDetails {
+	/** The verb this result answers. */
+	action: "write";
 	/** Absolute path of the written plan file. */
 	path: string;
 	/** How the path is shown: `~`-shortened, since plans live outside the project. */
@@ -85,8 +92,10 @@ export interface WritePlanDetails {
 	bytes: number;
 }
 
-/** Structured result carried in `set_plan_steps`'s `details`. */
+/** Structured result carried in the `plan` tool's `details` for `action: "steps"`. */
 export interface SetPlanStepsDetails {
+	/** The verb this result answers. */
+	action: "steps";
 	/** Absolute path of the plan file that was updated. */
 	path: string;
 	/** How the path is shown: `~`-shortened. */
@@ -99,8 +108,10 @@ export interface SetPlanStepsDetails {
 	total: number;
 }
 
-/** Structured result carried in `exit_plan_mode`'s `details`. */
+/** Structured result carried in the `plan` tool's `details` for `action: "exit"`. */
 export interface ExitPlanModeDetails {
+	/** The verb this result answers. */
+	action: "exit";
 	/** Whether the user approved the plan. */
 	approved: boolean;
 	/** The plan the model submitted, read from its file. */
@@ -121,8 +132,40 @@ export interface ExitPlanModeDetails {
 	unavailable?: boolean;
 }
 
-/** Structured result carried in `cancel_plan_mode`'s `details`. */
+/** Structured result carried in the `plan` tool's `details` for `action: "cancel"`. */
 export interface CancelPlanModeDetails {
+	/** The verb this result answers. */
+	action: "cancel";
 	/** True when plan mode was on and has now been turned off. */
 	cancelled: boolean;
 }
+
+/**
+ * A refused call: the reason, and the verb it named. It carries no `action`
+ * field on purpose — a refusal has none of that verb's state to report, and the
+ * absent discriminant is what tells a renderer it is looking at a rejection.
+ */
+export interface RefusedPlanDetails {
+	/** The verb the call named. */
+	refused: PlanAction;
+	/** Why the call was refused, as the model reads it. */
+	error: string;
+}
+
+/**
+ * What the `plan` tool's result carries: one of the five verbs, told apart by
+ * `action`, or a refusal that carried no state at all.
+ *
+ * The details name their own verb so a renderer draws the result it was given
+ * rather than re-reading the call's arguments, which a resumed transcript may
+ * no longer spell the same way. A details block recorded before the fold has no
+ * `action` at all, and a refusal never reaches the per-verb renderers; both take
+ * the same fallback.
+ */
+export type PlanDetails =
+	| EnterPlanModeDetails
+	| WritePlanDetails
+	| ExitPlanModeDetails
+	| SetPlanStepsDetails
+	| CancelPlanModeDetails
+	| RefusedPlanDetails;

package/extensions/plan/web-blocks.ts

@@ -59,13 +59,20 @@ export function setActive(planEl: ClientNode | null, index: number): number | nu
  * The index one step from `activeIndex`, or `null` when there is nothing to walk.
  *
  * With nothing active yet, `j` starts at the top and `k` at the bottom, which is what a
- * reader pressing either key on a fresh page expects.
+ * reader pressing either key on a fresh page expects. A view can hide blocks, and a
+ * hidden block is not a place the reader can be sent: the step lands on the next block
+ * they can actually see, or nowhere when the filter left none.
  */
 export function moveActive(planEl: ClientNode | null, activeIndex: number, delta: number): number | null {
 	const blocks = blockElements(planEl);
 	if (blocks.length === 0) return null;
-	const next = activeIndex < 0 ? (delta < 0 ? blocks.length - 1 : 0) : activeIndex + delta;
-	return setActive(planEl, next);
+	const step = delta < 0 ? -1 : 1;
+	const first =
+		activeIndex < 0 ? (step < 0 ? blocks.length - 1 : 0) : Math.min(Math.max(activeIndex + step, 0), blocks.length - 1);
+	for (let index = first; index >= 0 && index < blocks.length; index += step) {
+		if (blocks[index]?.hidden !== true) return setActive(planEl, index);
+	}
+	return null;
 }
 
 /**
@@ -85,5 +92,69 @@ export function blockAtLine(
 	return wrap && block ? { wrap, block } : null;
 }
 
-/** The block rules as source, for the client bundle. */
-export const WEB_BLOCKS_JS = [blockElements, setActive, moveActive, blockAtLine].map(String).join("\n\n");
+/** What the reader asked the plan to show. */
+export type ReviewView = "all" | "changed" | "comments";
+
+/** How much of the plan a view kept, so the page can say what it is hiding. */
+export interface ViewCounts {
+	shown: number;
+	hidden: number;
+}
+
+/**
+ * Keep the blocks a view asks for, and hide the rest.
+ *
+ * A view is a filter over what is drawn, not a second document: `All` restores every
+ * block, so the reader is one click from the whole plan, and the page's status line says
+ * how many were hidden so a filtered document never reads as a short one. Headings stay
+ * in every view — a paragraph without its section is a sentence without a subject — and a
+ * view with nothing to show keeps the document whole rather than blanking it.
+ */
+/**
+ * Keep the blocks a view asks for, and hide the rest.
+ *
+ * A view is a filter over what is drawn, not a second document: `All` restores every
+ * block, so the reader is one click from the whole plan, and the page's status line says
+ * how many were hidden so a filtered document never reads as a short one. Headings stay
+ * in every view — a paragraph without its section is a sentence without a subject — and a
+ * view with nothing to show keeps the document whole rather than blanking it. A comment
+ * thread is hidden with the block it hangs under: a note with no text it refers to reads
+ * as a comment on whatever happens to be above it.
+ */
+export function applyView(planEl: ClientNode | null, view: ReviewView): ViewCounts {
+	if (!planEl) return { shown: 0, hidden: 0 };
+	const blocks = blockElements(planEl);
+	const keep = (block: ClientNode): boolean =>
+		view === "all" ||
+		block.getAttribute("data-kind") === "heading" ||
+		(view === "changed"
+			? block.getAttribute("data-changed") === "1"
+			: (block.className || "").split(" ").indexOf("bf-block--commented") >= 0);
+	// A filter that matches nothing but the headings is not a view of the plan: showing an
+	// empty page is worse than showing the whole document beside the count.
+	const matched = blocks.filter((block) => block.getAttribute("data-kind") !== "heading" && keep(block)).length;
+	const whole = view !== "all" && blocks.length > 0 && matched === 0;
+	const visible: Record<string, boolean> = {};
+	for (const block of blocks) {
+		block.hidden = !whole && !keep(block);
+		if (!block.hidden) visible[block.getAttribute("data-line") ?? ""] = true;
+	}
+	const threads = planEl.querySelectorAll(".bf-comments");
+	for (let i = 0; i < threads.length; i++) {
+		const thread = threads[i];
+		if (!thread) continue;
+		const line = thread.getAttribute("data-line");
+		if (line !== null) thread.hidden = visible[line] !== true;
+	}
+	const shown = whole ? blocks.length : blocks.filter(keep).length;
+	return { shown, hidden: blocks.length - shown };
+}
+
+/**
+ * The block rules as source, for the client bundle.
+ *
+ * `applyView` travels with them because the page's view control calls it on every render:
+ * a name the bundle does not carry is a `ReferenceError` at the first repaint, which
+ * aborts the boot before the composer and the progress bar are wired.
+ */
+export const WEB_BLOCKS_JS = [blockElements, setActive, moveActive, blockAtLine, applyView].map(String).join("\n\n");

package/extensions/plan/web-chrome.ts

@@ -76,6 +76,10 @@ export const WEB_CHROME_JS = String.raw`  function setStatus(text, kind) {
     if (saveButton) saveButton.disabled = true;
     if (postButton) postButton.disabled = true;
     if (cancelButton) cancelButton.disabled = true;
+    // The rail's comment controls go with them: a settled review takes no new comment, and
+    // the frame renderer is the one rule that decides that, so this asks for a repaint
+    // rather than removing the buttons itself.
+    renderAll();
   }
 
   // A conflict means the file moved under the page; only a reload can re-anchor.