@plannotator/pi-extension 0.15.0 → 0.15.2

package/index.ts

@@ -2,9 +2,9 @@
  * Plannotator Pi Extension — File-based plan mode with visual browser review.
  *
  * Plans are written to PLAN.md on disk (git-trackable, editor-visible).
- * The agent calls exit_plan_mode to request approval; the user reviews
- * the plan in the Plannotator browser UI and can approve, deny with
- * annotations, or request changes.
+ * The agent calls plannotator_submit_plan to request approval; the user
+ * reviews the plan in the Plannotator browser UI and can approve, deny
+ * with annotations, or request changes.
  *
  * Features:
  * - /plannotator command or Ctrl+Alt+P to toggle
@@ -12,13 +12,13 @@
  * - --plan-file flag to customize the plan file path
  * - Bash unrestricted during planning (prompt-guided)
  * - Write restricted to plan file only during planning
- * - exit_plan_mode tool with browser-based visual approval
+ * - plannotator_submit_plan tool with browser-based visual approval
  * - [DONE:n] markers for execution progress tracking
  * - /plannotator-review command for code review
  * - /plannotator-annotate command for markdown annotation
  */
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { AgentMessage } from "@mariozechner/pi-agent-core";
@@ -35,6 +35,8 @@ import {
 	parseChecklist,
 } from "./generated/checklist.js";
 import { planDenyFeedback } from "./generated/feedback-templates.js";
+import { hasMarkdownFiles } from "./generated/resolve-file.js";
+import { FILE_BROWSER_EXCLUDED } from "./generated/reference-common.js";
 import { openBrowser } from "./server/network.js";
 import {
 	type AnnotateServerResult,
@@ -46,6 +48,12 @@ import {
 	startPlanReviewServer,
 	startReviewServer,
 } from "./server.js";
+import {
+	getToolsForPhase,
+	PLAN_SUBMIT_TOOL,
+	type Phase,
+	stripPlanningOnlyTools,
+} from "./tool-scope.js";
 
 // ── Types ──────────────────────────────────────────────────────────────
 
@@ -77,11 +85,6 @@ try {
 	// HTML not built yet — review feature will be unavailable
 }
 
-/** Extra tools to ensure are available during planning (on top of whatever is already active). */
-const PLANNING_EXTRA_TOOLS = ["grep", "find", "ls", "exit_plan_mode"];
-
-type Phase = "idle" | "planning" | "executing";
-
 function isAssistantMessage(m: AgentMessage): m is AssistantMessage {
 	return m.role === "assistant" && Array.isArray(m.content);
 }
@@ -177,28 +180,19 @@ export default function plannotator(pi: ExtensionAPI): void {
 	}
 
 	function persistState(): void {
-		pi.appendEntry("plannotator", { phase, planFilePath });
+		pi.appendEntry("plannotator", { phase, planFilePath, preplanTools });
 	}
 
 	/** Apply tool visibility for the current phase, preserving tools from other extensions. */
 	function applyToolsForPhase(): void {
-		if (phase === "planning") {
-			const base = preplanTools ?? pi.getActiveTools();
-			const toolSet = new Set(base);
-			for (const t of PLANNING_EXTRA_TOOLS) toolSet.add(t);
-			pi.setActiveTools([...toolSet]);
-		} else if (preplanTools) {
-			// Restore pre-plan tool set (removes exit_plan_mode, etc.)
-			pi.setActiveTools(preplanTools);
-			preplanTools = null;
-		}
-		// If no preplanTools (e.g. session restore to executing/idle), leave tools as-is
+		const baseTools = stripPlanningOnlyTools(preplanTools ?? pi.getActiveTools());
+		pi.setActiveTools(getToolsForPhase(baseTools, phase));
 	}
 
 	function enterPlanning(ctx: ExtensionContext): void {
 		phase = "planning";
 		checklistItems = [];
-		preplanTools = pi.getActiveTools();
+		preplanTools = stripPlanningOnlyTools(pi.getActiveTools());
 		applyToolsForPhase();
 		updateStatus(ctx);
 		updateWidget(ctx);
@@ -212,6 +206,7 @@ export default function plannotator(pi: ExtensionAPI): void {
 		phase = "idle";
 		checklistItems = [];
 		applyToolsForPhase();
+		preplanTools = null;
 		updateStatus(ctx);
 		updateWidget(ctx);
 		persistState();
@@ -343,11 +338,11 @@ export default function plannotator(pi: ExtensionAPI): void {
 	});
 
 	pi.registerCommand("plannotator-annotate", {
-		description: "Open markdown file in annotation UI",
+		description: "Open markdown file or folder in annotation UI",
 		handler: async (args, ctx) => {
 			const filePath = args?.trim();
 			if (!filePath) {
-				ctx.ui.notify("Usage: /plannotator-annotate <file.md>", "error");
+				ctx.ui.notify("Usage: /plannotator-annotate <file.md | folder/>", "error");
 				return;
 			}
 			if (!planHtmlContent) {
@@ -364,15 +359,41 @@ export default function plannotator(pi: ExtensionAPI): void {
 				return;
 			}
 
-			ctx.ui.notify(`Opening annotation UI for ${filePath}...`, "info");
+			// Check if the argument is a directory (folder annotation mode)
+			let isFolder = false;
+			try {
+				isFolder = statSync(absolutePath).isDirectory();
+			} catch {
+				ctx.ui.notify(`Cannot access: ${absolutePath}`, "error");
+				return;
+			}
+
+			let markdown: string;
+			let folderPath: string | undefined;
+			let mode: string | undefined;
+
+			if (isFolder) {
+				if (!hasMarkdownFiles(absolutePath, FILE_BROWSER_EXCLUDED)) {
+					ctx.ui.notify(`No markdown files found in ${absolutePath}`, "error");
+					return;
+				}
+				markdown = "";
+				folderPath = absolutePath;
+				mode = "annotate-folder";
+				ctx.ui.notify(`Opening annotation UI for folder ${filePath}...`, "info");
+			} else {
+				markdown = readFileSync(absolutePath, "utf-8");
+				ctx.ui.notify(`Opening annotation UI for ${filePath}...`, "info");
+			}
 
-			const markdown = readFileSync(absolutePath, "utf-8");
 			let server: AnnotateServerResult;
 			try {
 				server = await startAnnotateServer({
 					markdown,
 					filePath: absolutePath,
 					origin: "pi",
+					mode,
+					folderPath,
 					htmlContent: planHtmlContent,
 					sharingEnabled: process.env.PLANNOTATOR_SHARE !== "disabled",
 					shareBaseUrl: process.env.PLANNOTATOR_SHARE_URL || undefined,
@@ -389,8 +410,11 @@ export default function plannotator(pi: ExtensionAPI): void {
 			const result = await runBrowserReview(server, ctx);
 
 			if (result.feedback) {
+				const header = isFolder
+					? `# Markdown Annotations\n\nFolder: ${absolutePath}\n\n`
+					: `# Markdown Annotations\n\nFile: ${absolutePath}\n\n`;
 				pi.sendUserMessage(
-					`# Markdown Annotations\n\nFile: ${absolutePath}\n\n${result.feedback}\n\nPlease address the annotation feedback above.`,
+					`${header}${result.feedback}\n\nPlease address the annotation feedback above.`,
 				);
 			} else {
 				ctx.ui.notify("Annotation closed (no feedback).", "info");
@@ -519,14 +543,14 @@ export default function plannotator(pi: ExtensionAPI): void {
 		handler: async (ctx) => togglePlanMode(ctx),
 	});
 
-	// ── exit_plan_mode Tool ──────────────────────────────────────────────
+	// ── plannotator_submit_plan Tool ────────────────────────────────────
 
 	pi.registerTool({
-		name: "exit_plan_mode",
-		label: "Exit Plan Mode",
+		name: PLAN_SUBMIT_TOOL,
+		label: "Submit Plan",
 		description:
-			"Submit your plan for user review. " +
-			"Call this after drafting or revising your plan file. " +
+			"Submit your Plannotator plan for user review. " +
+			"Call this only while Plannotator planning mode is active, after drafting or revising your plan file. " +
 			"The user will review the plan in a visual browser UI and can approve, deny with feedback, or annotate it. " +
 			"If denied, use the edit tool to make targeted revisions (not write), then call this again.",
 		parameters: Type.Object({
@@ -561,7 +585,7 @@ export default function plannotator(pi: ExtensionAPI): void {
 					content: [
 						{
 							type: "text",
-							text: `Error: ${planFilePath} does not exist. Write your plan using the write tool first, then call exit_plan_mode again.`,
+							text: `Error: ${planFilePath} does not exist. Write your plan using the write tool first, then call ${PLAN_SUBMIT_TOOL} again.`,
 						},
 					],
 					details: { approved: false },
@@ -573,7 +597,7 @@ export default function plannotator(pi: ExtensionAPI): void {
 					content: [
 						{
 							type: "text",
-							text: `Error: ${planFilePath} is empty. Write your plan first, then call exit_plan_mode again.`,
+							text: `Error: ${planFilePath} is empty. Write your plan first, then call ${PLAN_SUBMIT_TOOL} again.`,
 						},
 					],
 					details: { approved: false },
@@ -587,6 +611,7 @@ export default function plannotator(pi: ExtensionAPI): void {
 			if (!ctx.hasUI || !planHtmlContent) {
 				phase = "executing";
 				applyToolsForPhase();
+				preplanTools = null;
 				persistState();
 				return {
 					content: [
@@ -624,6 +649,7 @@ export default function plannotator(pi: ExtensionAPI): void {
 			if (result.approved) {
 				phase = "executing";
 				applyToolsForPhase();
+				preplanTools = null;
 				updateStatus(ctx);
 				updateWidget(ctx);
 				persistState();
@@ -664,7 +690,7 @@ export default function plannotator(pi: ExtensionAPI): void {
 				content: [
 					{
 						type: "text",
-						text: planDenyFeedback(feedbackText, "exit_plan_mode", {
+						text: planDenyFeedback(feedbackText, PLAN_SUBMIT_TOOL, {
 							planFilePath,
 						}),
 					},
@@ -712,7 +738,7 @@ export default function plannotator(pi: ExtensionAPI): void {
 					content: `[PLANNOTATOR - PLANNING PHASE]
 You are in plan mode. You MUST NOT make any changes to the codebase — no edits, no commits, no installs, no destructive commands. The ONLY file you may write to or edit is the plan file: ${planFilePath}.
 
-Available tools: read, bash, grep, find, ls, write (${planFilePath} only), edit (${planFilePath} only), exit_plan_mode
+Available tools: read, bash, grep, find, ls, write (${planFilePath} only), edit (${planFilePath} only), ${PLAN_SUBMIT_TOOL}
 
 Do not run destructive bash commands (rm, git push, npm install, etc.) — focus on reading and exploring the codebase. Web fetching (curl, wget) is fine.
 
@@ -755,20 +781,20 @@ Keep the plan concise enough to scan quickly, but detailed enough to execute eff
 
 ### When to Submit
 
-Your plan is ready when you've addressed all ambiguities and it covers: what to change, which files to modify, what existing code to reuse, and how to verify. Call exit_plan_mode to submit for review.
+Your plan is ready when you've addressed all ambiguities and it covers: what to change, which files to modify, what existing code to reuse, and how to verify. Call ${PLAN_SUBMIT_TOOL} to submit for review.
 
 ### Revising After Feedback
 
 When the user denies a plan with feedback:
 1. Read ${planFilePath} to see the current plan.
 2. Use the edit tool to make targeted changes addressing the feedback — do NOT rewrite the entire file.
-3. Call exit_plan_mode again to resubmit.
+3. Call ${PLAN_SUBMIT_TOOL} again to resubmit.
 
 ### Ending Your Turn
 
 Your turn should only end by either:
 - Asking the user a question to gather more information.
-- Calling exit_plan_mode when the plan is ready for review.
+- Calling ${PLAN_SUBMIT_TOOL} when the plan is ready for review.
 
 Do not end your turn without doing one of these two things.`,
 					display: false,
@@ -867,6 +893,7 @@ Execute each step in order. After completing a step, include [DONE:n] in your re
 			phase = "idle";
 			checklistItems = [];
 			applyToolsForPhase();
+			preplanTools = null;
 			updateStatus(ctx);
 			updateWidget(ctx);
 			persistState();
@@ -893,11 +920,14 @@ Execute each step in order. After completing a step, include [DONE:n] in your re
 				(e: { type: string; customType?: string }) =>
 					e.type === "custom" && e.customType === "plannotator",
 			)
-			.pop() as { data?: { phase: Phase; planFilePath?: string } } | undefined;
+			.pop() as {
+				data?: { phase: Phase; planFilePath?: string; preplanTools?: string[] | null };
+			} | undefined;
 
 		if (stateEntry?.data) {
 			phase = stateEntry.data.phase ?? phase;
 			planFilePath = stateEntry.data.planFilePath ?? planFilePath;
+			preplanTools = stateEntry.data.preplanTools ?? preplanTools;
 		}
 
 		// Rebuild execution state from disk + session messages
@@ -934,10 +964,9 @@ Execute each step in order. After completing a step, include [DONE:n] in your re
 			}
 		}
 
-		// Apply tool restrictions for current phase
-		if (phase === "planning") {
-			applyToolsForPhase();
-		}
+		// Re-apply tool visibility on startup/resume so planning-only tools stay hidden
+		// outside planning and pre-plan tool state is restored after approvals.
+		applyToolsForPhase();
 
 		updateStatus(ctx);
 		updateWidget(ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/pi-extension",
-  "version": "0.15.0",
+  "version": "0.15.2",
   "type": "module",
   "description": "Plannotator extension for Pi coding agent - interactive plan review with visual annotation",
   "author": "backnotprop",
@@ -28,7 +28,7 @@
     "review-editor.html"
   ],
   "scripts": {
-    "build": "cp ../hook/dist/index.html plannotator.html && cp ../hook/dist/review.html review-editor.html && mkdir -p generated && for f in feedback-templates review-core storage draft project pr-provider pr-github pr-gitlab checklist integrations-common repo reference-common favicon resolve-file; do src=\"../../packages/shared/$f.ts\"; printf '// @generated — DO NOT EDIT. Source: packages/shared/%s.ts\\n' \"$f\" | cat - \"$src\" > \"generated/$f.ts\"; done",
+    "build": "cp ../hook/dist/index.html plannotator.html && cp ../hook/dist/review.html review-editor.html && mkdir -p generated && for f in feedback-templates review-core storage draft project pr-provider pr-github pr-gitlab checklist integrations-common repo reference-common favicon resolve-file; do src=\"../../packages/shared/$f.ts\"; printf '// @generated — DO NOT EDIT. Source: packages/shared/%s.ts\\n' \"$f\" | cat - \"$src\" > \"generated/$f.ts\"; done && mkdir -p generated/ai/providers && for f in index types provider session-manager endpoints context base-session; do src=\"../../packages/ai/$f.ts\"; printf '// @generated — DO NOT EDIT. Source: packages/ai/%s.ts\\n' \"$f\" | cat - \"$src\" > \"generated/ai/$f.ts\"; done && for f in claude-agent-sdk codex-sdk opencode-sdk pi-sdk pi-sdk-node pi-events; do src=\"../../packages/ai/providers/$f.ts\"; printf '// @generated — DO NOT EDIT. Source: packages/ai/providers/%s.ts\\n' \"$f\" | cat - \"$src\" > \"generated/ai/providers/$f.ts\"; done",
     "prepublishOnly": "cd ../.. && bun run build:pi"
   },
   "peerDependencies": {