@gavin-hu/my-pi-agent 0.21.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, NO_SERVER_DEPS, 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, NO_SERVER_DEPS),
+	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-client.ts

@@ -23,6 +23,7 @@ import {
 	CLIENT_BASE_JS,
 	CLIENT_RUNTIME_JS,
 	dialogScript,
+	INLINE_MARKDOWN_JS,
 	keysDialogScript,
 	THEME_TOGGLE_JS,
 } from "../../lib/web/index.ts";
@@ -125,6 +126,8 @@ ${WEB_COMMENTS_JS}
 
 ${WEB_COLLAB_JS}
 
+${INLINE_MARKDOWN_JS}
+
 ${WEB_MARKDOWN_JS}
 
   // Review facts: the plan's step progress, and the comments per section.

package/extensions/plan/web-lazy.ts

@@ -0,0 +1,53 @@
+/**
+ * The plan review server, loaded when a review first asks for it.
+ *
+ * The browser review owns `lib/http`, the web kit, and the plan page; none of it
+ * is needed to register `/plan` or the plan tools. `index.ts`, `commands.ts`, and
+ * `tools.ts` therefore share this proxy over `lib/lazy`: the first review loads
+ * `web.ts` once, and `closeAll` on shutdown only closes a review that was already
+ * opened, so a session that never reviewed a plan imports none of the server.
+ *
+ * The synchronous reads (`current`, `shareState`) answer `undefined` until the
+ * module is loaded, which is the truth: no review can be open before a load.
+ */
+
+import { lazy } from "../../lib/lazy.ts";
+import type { PlanStore } from "./plans.ts";
+import type { PlanWebReview, PlanWebReviewDeps } from "./web.ts";
+
+/** The review module, as the proxy loads it. */
+export type PlanWebModule = typeof import("./web.ts");
+
+/** How the proxy reaches the review module; production uses the dynamic import. */
+export type PlanWebLoader = () => Promise<PlanWebModule>;
+
+/**
+ * The deps a caller that injects its own review leaves out.
+ *
+ * A review needs a place on the session's server, so a caller with no wiring says so
+ * rather than binding a socket of its own: the start is refused with a sentence.
+ */
+export const NO_SERVER_DEPS: PlanWebReviewDeps = {
+	mount: async () => ({ kind: "refused", reason: "this review has no server wired" }),
+	session: () => "",
+};
+
+export function createLazyPlanWebReview(
+	store: PlanStore,
+	deps: PlanWebReviewDeps,
+	load: PlanWebLoader = () => import("./web.ts"),
+): PlanWebReview {
+	const review = lazy(async () => (await load()).createPlanWebReview(store, deps));
+	return {
+		start: async (cwd, plan, options) => (await review.get()).start(cwd, plan, options),
+		current: () => review.peek()?.current(),
+		share: async () => (await review.get()).share(),
+		stopSharing: async () => (await review.get()).stopSharing(),
+		shareState: () => review.peek()?.shareState(),
+		// Shutdown must not start a load: a review that never opened has nothing to close.
+		closeAll: async () => {
+			const opened = review.peek();
+			if (opened !== undefined) await opened.closeAll();
+		},
+	};
+}

package/extensions/plan/web-markdown.ts

@@ -1,76 +1,18 @@
 /**
- * The Markdown half of the review client script.
+ * The block half of the plan review's Markdown: tables, fenced code, headings, quotes,
+ * and lists.
  *
  * It is a fragment of the same IIFE `web-client.ts` ships (`WEB_MARKDOWN_JS` is
  * interpolated into `REVIEW_CLIENT_JS`), kept in its own module so the client's
- * event wiring and its document rendering are read one at a time. Every value it
- * writes is a DOM text node: plan and comment text never becomes markup, and the
- * only HTML it copies is the server's own `tok-*` spans.
+ * event wiring and its document rendering are read one at a time. The text inside a
+ * block is rendered by `renderInline`, which crosses from `lib/web/markdown.ts` with
+ * the board's card notes — one inline grammar and one link policy for both pages.
+ *
+ * Every value it writes is a DOM text node: plan and comment text never becomes markup,
+ * and the only HTML it copies is the server's own `tok-*` spans.
  */
 
-export const WEB_MARKDOWN_JS = String.raw`  // A link is rendered only for an http(s) or mailto target. Resolving against
-  // the review origin is what catches a target that only looks relative: the
-  // URL parser strips a tab or newline, so "/\t/evil.com" is cross-origin once
-  // it is parsed, and a disguised target must stay text.
-  function safeHref(url, base) {
-    var trimmed = String(url).trim();
-    if (!trimmed || /^\/\//.test(trimmed)) return null;
-    var resolved;
-    try { resolved = new URL(trimmed, base); } catch (error) { return null; }
-    if (resolved.protocol === "mailto:") return trimmed;
-    if (resolved.protocol !== "http:" && resolved.protocol !== "https:") return null;
-    if (resolved.username || resolved.password) return null;
-    if (resolved.origin === new URL(base).origin) return resolved.href;
-    return /^https?:\/\//i.test(trimmed) ? resolved.href : null;
-  }
-
-  // Inline token order matters: code, emphasis, and links are matched before a
-  // bare URL, so a URL inside a link target or a code span is never re-split.
-  var INLINE = /(\x60[^\x60]+\x60|\*\*[^*]+\*\*|\*[^*]+\*|\[[^\]]+\]\([^)]+\)|(?:https?:\/\/|www\.)[^\s<]+)/g;
-
-  function renderInline(container, text) {
-    String(text).split(INLINE).forEach(function (part) {
-      if (!part) return;
-      var match;
-      if ((match = /^\x60([^\x60]+)\x60$/.exec(part))) {
-        var code = el("code"); code.textContent = match[1]; container.appendChild(code); return;
-      }
-      if ((match = /^\*\*([^*]+)\*\*$/.exec(part))) {
-        var strong = el("strong"); strong.textContent = match[1]; container.appendChild(strong); return;
-      }
-      if ((match = /^\*([^*]+)\*$/.exec(part))) {
-        var em = el("em"); em.textContent = match[1]; container.appendChild(em); return;
-      }
-      if ((match = /^\[([^\]]+)\]\(([^)]+)\)$/.exec(part))) {
-        var href = safeHref(match[2], location.href);
-        if (!href) { container.appendChild(document.createTextNode(part)); return; }
-        var link = el("a"); link.textContent = match[1]; link.href = href; link.target = "_blank"; link.rel = "noreferrer noopener";
-        container.appendChild(link); return;
-      }
-      // GFM extended autolink: a bare http(s) or www. URL in running text.
-      if ((match = /^(?:https?:\/\/|www\.)[^\s<]+$/.exec(part))) {
-        var url = match[0].replace(/[.,;:!?*_~]+$/, "");
-        while (url.charAt(url.length - 1) === ")" && (url.match(/\(/g) || []).length < (url.match(/\)/g) || []).length) {
-          url = url.slice(0, -1).replace(/[.,;:!?*_~]+$/, "");
-        }
-        var dot = url.indexOf(".");
-        var target = /^www\./i.test(url) ? "http://" + url : url;
-        var safe = dot > 0 && /\.[^./]/.test(url.slice(dot)) ? safeHref(target, location.href) : null;
-        if (safe) {
-          var auto = el("a");
-          auto.textContent = url;
-          auto.href = safe;
-          auto.target = "_blank";
-          auto.rel = "noreferrer noopener";
-          container.appendChild(auto);
-          return;
-        }
-      }
-      container.appendChild(document.createTextNode(part));
-    });
-  }
-
-  // Copy only text and tok-* spans out of server-highlighted HTML, so a code
+export const WEB_MARKDOWN_JS = String.raw`  // Copy only text and tok-* spans out of server-highlighted HTML, so a code
   // line can never introduce markup even though it arrives as a string.
   function copyTokens(from, to) {
     Array.prototype.forEach.call(from.childNodes, function (node) {

package/extensions/plan/web-payload.ts

@@ -60,7 +60,7 @@ export interface ReviewPageData {
 	outline: ReviewOutlineItem[];
 	/**
 	 * The plan's step progress, from the same `extractPlanSteps` the approval and
-	 * `set_plan_steps` use: the `Steps` section when there is one, so the page
+	 * the `steps` action use: the `Steps` section when there is one, so the page
 	 * agrees with what approval seeds rather than counting every checkbox.
 	 */
 	steps: { done: number; total: number };
@@ -71,7 +71,7 @@ export interface ReviewPageData {
 	 * count, comment length, and quote length, from `feedback.ts`.
 	 */
 	limits: { comments: number; comment: number; quote: number };
-	/** Whether the review may approve the plan (only the `exit_plan_mode` flow). */
+	/** Whether the review may approve the plan (only the `plan` tool's `exit` flow). */
 	canApprove: boolean;
 	/** Who is looking: `owner` may approve, `reviewer` may only comment. */
 	role: ReviewRole;
@@ -150,7 +150,7 @@ export function reviewPageData(input: ReviewPayloadInput): ReviewPageData {
 					},
 				],
 	);
-	// The same step list approval seeds and set_plan_steps indexes, so the page's
+	// The same step list approval seeds and the `steps` action indexes, so the page's
 	// progress cannot disagree with the todo list.
 	const stepList = extractPlanSteps(current);
 	// Highlight code blocks once, at the boundary: the client copies only the tok-*

package/extensions/plan/web-router.ts

@@ -1,10 +1,11 @@
 /**
  * The request router for browser plan review.
  *
- * A request is validated (method, `Host`, origin, token), matched to a route,
- * and answered with a plain {@link ServeResponse}, so every route can be tested
- * without a socket. The `/events` route is a marker: the node server in `web.ts`
- * keeps that response open as a Server-Sent Events stream.
+ * A request is validated (method, `Host`, origin, token, and — on a route that
+ * reads a body — that the body is JSON), matched to a route, and answered with a
+ * plain {@link ServeResponse}, so every route can be tested without a socket. The
+ * `/events` route is a marker: the node server in `web.ts` keeps that response open
+ * as a Server-Sent Events stream.
  *
  * The token is a per-session secret carried in the page URL, and on a shared
  * review it is the only credential a reviewer has: it names the caller — the
@@ -20,6 +21,7 @@ import {
 	pageHeaders,
 	parseRequestUrl,
 	postOnly,
+	requireJsonBody,
 	scriptHeaders,
 	type ServeResponse,
 } from "../../lib/http/index.ts";
@@ -40,7 +42,7 @@ export interface ReviewContext {
 	caller: (token: string) => ReviewCaller | undefined;
 	/** The host names this server answers to now, so a rebound page is refused. */
 	hosts: () => readonly string[];
-	/** Whether the browser may approve the plan (only the `exit_plan_mode` flow). */
+	/** Whether the browser may approve the plan (only the `plan` tool's `exit` flow). */
 	canApprove: boolean;
 	/** Build the page data for the caller (recomputed per request). */
 	page: (caller: ReviewCaller) => Promise<ReviewPageData>;
@@ -157,7 +159,9 @@ export async function handleReviewRequest(
 	}
 	if (pathname === "/api/share/revoke") {
 		const refusal =
-			postOnly(method, "revoke a link") ?? roleOnly(caller, ["owner"], "Only the plan owner can revoke a link.");
+			postOnly(method, "revoke a link") ??
+			requireJsonBody(headers["content-type"]) ??
+			roleOnly(caller, ["owner"], "Only the plan owner can revoke a link.");
 		if (refusal) return refusal;
 		const id = linkIdOf(body);
 		if (id === undefined) return jsonError(400, "The request body must name the link's id.");
@@ -169,7 +173,9 @@ export async function handleReviewRequest(
 		// A reviewer's whole surface: persist the comments they wrote and end
 		// nothing. Only the owner's own save decides the review.
 		const refusal =
-			postOnly(method, "post comments") ?? roleOnly(caller, ["reviewer"], "Only a shared reviewer posts comments.");
+			postOnly(method, "post comments") ??
+			requireJsonBody(headers["content-type"]) ??
+			roleOnly(caller, ["reviewer"], "Only a shared reviewer posts comments.");
 		if (refusal) return refusal;
 		const annotations = parseAnnotations(body);
 		if (isResponse(annotations)) return annotations;
@@ -182,6 +188,7 @@ export async function handleReviewRequest(
 		// `/api/comment`, so this route can never settle a shared review.
 		const refusal =
 			postOnly(method, "save feedback") ??
+			requireJsonBody(headers["content-type"]) ??
 			roleOnly(caller, ["owner"], "Only the plan owner saves this review; a reviewer posts comments.");
 		if (refusal) return refusal;
 		const annotations = parseAnnotations(body);
@@ -192,10 +199,12 @@ export async function handleReviewRequest(
 		return jsonResponse(200, { ok: true });
 	}
 	if (pathname === "/api/approve") {
-		// Only the owner's own page approves, and only the exit_plan_mode flow owns
+		// Only the owner's own page approves, and only the `exit` flow owns
 		// the side effects: a reviewer token is refused whatever it posts.
 		const refusal =
-			postOnly(method, "approve") ?? roleOnly(caller, ["owner"], "A shared review cannot approve the plan.");
+			postOnly(method, "approve") ??
+			requireJsonBody(headers["content-type"]) ??
+			roleOnly(caller, ["owner"], "A shared review cannot approve the plan.");
 		if (refusal) return refusal;
 		if (!ctx.canApprove) return jsonError(403, "This review cannot be approved from the browser.");
 		const annotations = parseAnnotations(body);