@janvitos/pi-plan-build 0.1.51 → 0.1.54

package/README.md

@@ -29,7 +29,7 @@ Optionally keep the approved plan visible in a docked side panel while implement
 - The custom composer uses OpenCode prompt-inspired blue/orange mode colors on the rounded top-left border and left rail, complemented by Pi's border color on the right rail and rounded bottom-right border; rounded corners inherit their vertical rail colors while horizontal `╌` segments bridge the borders at both junctions, paired with a light vertical `┆` at the top right and a mode-specific bottom-left transition: thin `┆` in Plan and heavy `┇` in Build. The active composer and submitted user messages use a continuous solid thin `│` left rail in both modes. These rails use the active Pi theme's `warning` color in Plan and `thinkingLow` color in Build, and submitted messages retain their original mode after mode changes and session restores. Its metadata row shows mode, model, provider, and thinking level; cycling the thinking level updates that row directly.
 - Pi Plan Build leaves the footer untouched; Pi or another installed extension remains responsible for path, usage, model, provider, thinking, and extension-status information.
 - `/plan`, `/build`, and the `--plan` startup flag.
-- Per-session plans at `~/.pi/agent/plans/<session-id>.md`.
+- Per-task plans at `~/.pi/agent/plans/<session-id>-001.md`, `-002.md`, etc., with the active plan and completion status persisted in the session. Existing `<session-id>.md` plans remain usable.
 - In Plan mode, built-in `edit` and `write` are restricted to the exact plan file.
 - Interactive `question`, `plan_enter`, and `plan_exit` tools.
 - Plan mode supports read-only conversation and research across multiple turns, then persists the final plan when it is ready for approval.
@@ -41,7 +41,7 @@ Optionally keep the approved plan visible in a docked side panel while implement
 - **Experimental:** In fullscreen TUI, valid checklist plans also offer **Implement step by step** when Pi Plan Build owns the optional fullscreen layout: a passive, non-overlapping docked right panel keeps the plan visible while natural-language prompts gate steps and report completed work. The panel is visual-only and never captures keyboard input. This feature is still under active development.
 - Compatible editor decorators can wrap Pi Plan Build's editor without disabling its composer. If another extension replaces rather than invokes that editor, already owns the editor before Plan Build starts, or replaces the fullscreen layout, Plan Build automatically uses reduced UI: it keeps the core Plan/Build workflow and mode status but does not replace that editor or offer a new step-by-step panel.
 - Staying in Plan mode—or pressing Escape in the approval dialog—produces a durable acknowledgement and stops the run until the user responds.
-- Mode state and mode-specific tool availability survive compactions, reloads, resumes, and forks.
+- Plan mode state survives compactions, reloads, resumes, and forks.
 - When Pi Plan Build's custom editor is active and Pi recreates it, the latest 100 user prompts from the active session branch are restored for Up/Down history navigation.
 
 ## Requirements
@@ -82,13 +82,23 @@ Do not install more than one npm, Git, or local copy at the same time; duplicate
 | --- | --- |
 | `Alt+M` | Cycle Build and Plan in any TUI setup |
 | `Tab` | With the custom composer active, cycle modes or accept an active autocomplete selection |
-| `/plan` | Select Plan mode |
+| `/plan` | Resume the unfinished plan, or select a new plan file after completion |
+| `/plan new` | Start a separate task in Plan mode, preserving previous plan files and clearing previous step execution |
+| `/plan done` | In Build mode, explicitly mark the saved plan's implementation complete |
 | `/build` | Select Build mode |
 | `pi --plan` | Start a new session in Plan mode |
 | `/build-fresh` | Start a pending clean-session implementation manually |
 
 The agent may also enter Plan mode with `plan_enter` when planning or investigation is safer than immediate execution.
 
+### Plan lifecycle
+
+One task uses one plan file across discussion, revisions, approval, and temporary mode changes. Approval or the end of an agent turn does **not** mark implementation complete. For normal Build execution, the agent calls `plan_complete` after finishing implementation and required verification; `/plan done` is the manual equivalent. Completing the final step in step-by-step execution also marks the plan complete. The next entry into Plan mode selects a new numbered file without modifying the old one.
+
+Use `/plan new` for an unrelated task before the current plan is finished. It preserves existing files but clears the previous step-by-step execution and pending fresh-session handoff. `/plan new` and `/plan done` require an idle agent. Cancelling step execution does not mark a plan complete.
+
+Plan files are written only when finalizing or revising, not merely when selecting a new task. Reload/resume restores the active file and lifecycle; forks copy the tracked plan into the child session's own file. Legacy unnumbered files are retained without renaming.
+
 ### Plan approval
 
 When planning is complete, `plan_exit` displays the entire persisted plan and asks whether to:
@@ -136,7 +146,7 @@ The integration uses Pi 0.84.2's public fullscreen layout primitives plus a guar
 
 Normal tools remain visible so the model can inspect the project. While a Plan run is active:
 
-- `edit` and `write` are permitted only for the canonical session plan file;
+- `edit` and `write` are permitted only for the active task's plan file;
 - the Plan prompt reserves those mutations for finalizing or explicitly revising the plan, not ordinary conversation or research;
 - other `edit` and `write` calls are blocked by the extension;
 - bash is not restricted at the permission layer, but the Plan prompt explicitly permits read-only exploration only.

package/index.ts

@@ -39,6 +39,8 @@ import {
 	classifyPlanExitChoice,
 	type FreshImplementationRequest,
 	decodeModeState,
+	decodePlanLifecycle,
+	type PlanLifecycle,
 	extractPromptHistory,
 	formatModeMetadata,
 	formatModeRail,
@@ -71,7 +73,7 @@ const STATUS_KEY = "pi-plan-build-mode";
 const PLAN_STEP_CHOICE = "Implement step by step";
 const PANEL_WIDTH = 64;
 const PANEL_MIN_TERMINAL_WIDTH = 132;
-const MANAGED_TOOLS = new Set(["question", "plan_enter", "plan_exit", "plan_step_control", "plan_step_complete"]);
+const MANAGED_TOOLS = new Set(["question", "plan_enter", "plan_exit", "plan_step_control", "plan_step_complete", "plan_complete"]);
 const MODE_ADDED_TOOLS = new Set([...MANAGED_TOOLS, "edit", "write"]);
 const EMPTY_PARAMETERS = Type.Object({});
 
@@ -83,6 +85,8 @@ interface StoredState {
 	pendingReminder?: "plan" | "build";
 	toolsBeforeModes?: string[];
 	execution?: PlanExecutionState;
+	plan?: PlanLifecycle;
+	planSessionId?: string;
 }
 
 function shorten(filePath: string, cwd: string): string {
@@ -97,6 +101,7 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 	let runMode: Mode | undefined;
 	let pendingReminder: PendingReminder;
 	let planPath = "";
+	let planLifecycle: PlanLifecycle = { sequence: 1, status: "open" };
 	let toolsBeforeModes: string[] = [];
 	let currentContext: ExtensionContext | undefined;
 	let requestEditorRender: (() => void) | undefined;
@@ -154,7 +159,7 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 	pi.registerEntryRenderer(PLAN_STEP_GUIDANCE_ENTRY_TYPE, renderPlanStepGuidance);
 
 	function stateData(): StoredState {
-		return { version: 1, selectedMode, pendingReminder, toolsBeforeModes, ...(execution ? { execution } : {}) };
+		return { version: 1, selectedMode, pendingReminder, toolsBeforeModes, plan: { ...planLifecycle }, planSessionId: currentContext?.sessionManager.getSessionId(), ...(execution ? { execution } : {}) };
 	}
 
 	function persist(): void {
@@ -236,6 +241,7 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 			return undefined;
 		}
 		const summary = formatPlanCompletionSummary(next);
+		planLifecycle = { ...planLifecycle, status: "completed" };
 		execution = undefined;
 		removePanelLayout();
 		persist();
@@ -298,6 +304,7 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 				...base,
 				"question",
 				"plan_enter",
+				...(!execution && planLifecycle.status === "open" && fs.existsSync(planPath) ? ["plan_complete"] : []),
 				...(execution && execution.status !== "completed" ? ["plan_step_control"] : []),
 				...(activePlanStep(execution) ? ["plan_step_complete"] : []),
 			]));
@@ -314,7 +321,36 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 			: `No plan file exists yet. When ready to finalize, create your plan at ${planPath} using the write tool.`;
 	}
 
+	function startNewPlan(ctx: ExtensionContext): void {
+		let sequence = planLifecycle.sequence;
+		for (const entry of ctx.sessionManager.getEntries()) {
+			if (entry.type !== "custom" || entry.customType !== STATE_TYPE) continue;
+			const saved = decodePlanLifecycle((entry.data as StoredState | undefined)?.plan);
+			if (saved) sequence = Math.max(sequence, saved.sequence);
+		}
+		do {
+			planPath = makePlanPath(path.join(getAgentDir(), "plans"), ctx.sessionManager.getSessionId(), ++sequence);
+		} while (fs.existsSync(planPath));
+		planLifecycle = { sequence, status: "open" };
+		freshImplementationRequest = undefined;
+		execution = undefined;
+		removePanelLayout();
+		pendingReminder = "plan";
+		persist();
+	}
+
+	function completeCurrentPlan(): void {
+		if ((runMode ?? selectedMode) !== "build") throw new Error("Switch to Build mode before completing implementation");
+		if (execution) throw new Error("Complete or cancel the step-by-step execution first");
+		if (!fs.existsSync(planPath)) throw new Error("No saved plan to complete");
+		planLifecycle = { ...planLifecycle, status: "completed" };
+		freshImplementationRequest = undefined;
+		persist();
+		applyTools("build");
+	}
+
 	async function selectMode(mode: Mode, ctx: ExtensionContext, source: "manual" | "tool"): Promise<void> {
+		if (mode === "plan" && planLifecycle.status === "completed" && (source === "tool" || ctx.isIdle())) startNewPlan(ctx);
 		if (mode === selectedMode && (source === "manual" || mode === runMode)) return;
 		const previous = selectedMode;
 		if (mode === "plan") await ensurePlanDirectory();
@@ -336,8 +372,32 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 	}
 
 	pi.registerCommand("plan", {
-		description: "Switch to Plan mode",
-		handler: async (_args, ctx) => selectMode("plan", ctx, "manual"),
+		description: "Switch to Plan mode; new starts a separate task, done marks implementation complete",
+		getArgumentCompletions: (prefix) => ["new", "done"].filter((value) => value.startsWith(prefix)).map((value) => ({ value, label: value })),
+		handler: async (args, ctx) => {
+			const action = args.trim();
+			if (!action) return selectMode("plan", ctx, "manual");
+			if (action !== "new" && action !== "done") {
+				ctx.ui.notify("Usage: /plan [new|done]", "warning");
+				return;
+			}
+			if (!ctx.isIdle()) {
+				ctx.ui.notify("Wait for the agent to finish before changing the active plan.", "warning");
+				return;
+			}
+			if (action === "done") {
+				try {
+					completeCurrentPlan();
+					ctx.ui.notify("Plan completed. The next planning task will use a new file.", "info");
+				} catch (error) {
+					ctx.ui.notify(error instanceof Error ? error.message : String(error), "warning");
+				}
+				return;
+			}
+			startNewPlan(ctx);
+			await selectMode("plan", ctx, "manual");
+			ctx.ui.notify(`New plan: ${shorten(planPath, ctx.cwd)}. Previous plan files are preserved.`, "info");
+		},
 	});
 	pi.registerCommand("build", {
 		description: "Switch to Build mode",
@@ -402,6 +462,7 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 							destinationPlanPath = makePlanPath(
 								path.join(getAgentDir(), "plans"),
 								sessionManager.getSessionId(),
+								1,
 							);
 							await fs.promises.mkdir(path.dirname(destinationPlanPath), { recursive: true });
 							await fs.promises.writeFile(destinationPlanPath, request.plan, "utf8");
@@ -412,6 +473,8 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 								selectedMode: "build",
 								pendingReminder: "build",
 								toolsBeforeModes: sourceTools,
+								plan: { sequence: 1, status: "open" },
+								planSessionId: sessionManager.getSessionId(),
 							} satisfies StoredState);
 						} catch (error: unknown) {
 							setupError = error instanceof Error ? error.message : String(error);
@@ -458,6 +521,22 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 		},
 	});
 
+	pi.registerTool({
+		name: "plan_complete",
+		label: "Complete Plan",
+		description: "Mark the current saved plan complete only after its implementation and required verification are finished, or the user explicitly confirms completion. Do not call for partial work, pauses, errors, or merely approving a plan. Preserves the plan file; the next planning task gets a new file.",
+		promptGuidelines: ["Call plan_complete when the current saved plan has been fully implemented and verified; do not infer completion merely from the end of a turn."],
+		parameters: EMPTY_PARAMETERS,
+		executionMode: "sequential",
+		async execute() {
+			completeCurrentPlan();
+			return {
+				content: [{ type: "text", text: "Plan marked complete and preserved. Summarize the implementation and verification for the user." }],
+				details: { planPath, completed: true },
+			};
+		},
+	});
+
 	pi.registerTool({
 		name: "plan_enter",
 		label: "Enter Plan Mode",
@@ -606,6 +685,8 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 		name: "plan_exit",
 		label: "Exit Plan Mode",
 		description: PLAN_EXIT_DESCRIPTION,
+		promptSnippet: "Display the saved plan and request user approval",
+		promptGuidelines: ["Call plan_exit after finalizing the saved plan when the user asks to show, review, or approve it."],
 		parameters: EMPTY_PARAMETERS,
 		executionMode: "sequential",
 		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
@@ -733,6 +814,7 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 		applyTools(runMode);
 		let content: string | undefined;
 		if (runMode === "plan") {
+			if (planLifecycle.status === "completed") startNewPlan(ctx);
 			await ensurePlanDirectory();
 			content = buildPlanReminder(describePlanFile());
 		} else if (activePlanStep(execution)) {
@@ -742,7 +824,7 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 			content = buildPlanStepWaitingReminder(execution.steps.map((step, index) => `${index + 1}. [${step.status}] ${step.text}`).join("\n"));
 		} else if (pendingReminder === "build") {
 			content = PLAN_TO_BUILD_REMINDER;
-			if (fs.existsSync(planPath)) content += `\n\nA plan file exists at ${planPath}. You should execute the plan defined within it.`;
+			if (planLifecycle.status === "open" && fs.existsSync(planPath)) content += `\n\nA plan file exists at ${planPath}. You should execute the plan defined within it.`;
 		}
 		pendingReminder = undefined;
 		persist();
@@ -750,10 +832,6 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 		return { message: { customType: "pi-plan-build-reminder", content, display: false } };
 	});
 
-	pi.on("turn_end", () => {
-		applyTools(runMode ?? selectedMode);
-	});
-
 	pi.on("agent_settled", async (_event, ctx) => {
 		runMode = undefined;
 		applyTools(selectedMode);
@@ -774,7 +852,7 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 		composerMountingEditorFactory = undefined;
 		reducedOptionalUi = false;
 		reducedUiNoticeShown = false;
-		const entries = ctx.sessionManager.getEntries();
+		const entries = ctx.sessionManager.getBranch();
 		const latest = entries
 			.filter(
 				(entry: any) =>
@@ -791,7 +869,18 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 		toolsBeforeModes = Array.isArray(raw?.toolsBeforeModes)
 			? raw.toolsBeforeModes.filter((name): name is string => typeof name === "string" && !MANAGED_TOOLS.has(name))
 			: pi.getActiveTools().filter((name) => !MANAGED_TOOLS.has(name));
-		planPath = makePlanPath(path.join(getAgentDir(), "plans"), ctx.sessionManager.getSessionId());
+		const plansDir = path.join(getAgentDir(), "plans");
+		const legacyPath = makePlanPath(plansDir, ctx.sessionManager.getSessionId());
+		planLifecycle = decodePlanLifecycle(raw?.plan) ?? { sequence: fs.existsSync(legacyPath) || execution ? 0 : 1, status: "open" };
+		planPath = makePlanPath(plansDir, ctx.sessionManager.getSessionId(), planLifecycle.sequence);
+		if (event.reason === "fork" && typeof raw?.planSessionId === "string" && raw.planSessionId !== ctx.sessionManager.getSessionId()) {
+			const sourcePath = makePlanPath(plansDir, raw.planSessionId, planLifecycle.sequence);
+			if (fs.existsSync(sourcePath) && !fs.existsSync(planPath)) {
+				await ensurePlanDirectory();
+				await fs.promises.copyFile(sourcePath, planPath, fs.constants.COPYFILE_EXCL);
+			}
+		}
+		persist();
 		if (selectedMode === "plan" || execution) await ensurePlanDirectory();
 		if (execution && !fs.existsSync(planPath)) await fs.promises.writeFile(planPath, execution.planMarkdown, "utf8");
 		applyTools(selectedMode);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@janvitos/pi-plan-build",
-  "version": "0.1.51",
+  "version": "0.1.54",
   "description": "Plan safely, approve explicitly, then implement here or in a clean session.",
   "type": "module",
   "license": "MIT",
@@ -33,7 +33,7 @@
     "access": "public"
   },
   "scripts": {
-    "test": "node --experimental-strip-types --test utils.test.ts question-ui.test.ts plan-execution.test.ts plan-panel.test.ts user-message-rail.test.ts ui-compat.test.ts",
+    "test": "node --experimental-strip-types --test utils.test.ts question-ui.test.ts plan-execution.test.ts plan-panel.test.ts user-message-rail.test.ts ui-compat.test.ts plan-lifecycle.test.ts",
     "prepublishOnly": "npm test"
   },
   "peerDependencies": {

package/utils.ts

@@ -230,9 +230,24 @@ export function sanitizeSessionId(value: string | undefined): string {
 	return cleaned || "ephemeral";
 }
 
-export function makePlanPath(plansDir: string, sessionId: string | undefined): string {
+export interface PlanLifecycle {
+	sequence: number;
+	status: "open" | "completed";
+}
+
+export function decodePlanLifecycle(value: unknown): PlanLifecycle | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const candidate = value as Partial<PlanLifecycle>;
+	if (!Number.isSafeInteger(candidate.sequence) || candidate.sequence! < 0 ||
+		(candidate.status !== "open" && candidate.status !== "completed")) return undefined;
+	return { sequence: candidate.sequence!, status: candidate.status };
+}
+
+export function makePlanPath(plansDir: string, sessionId: string | undefined, sequence = 0): string {
+	if (!Number.isSafeInteger(sequence) || sequence < 0) throw new Error("Invalid plan sequence");
 	const root = path.resolve(plansDir);
-	const candidate = path.resolve(root, `${sanitizeSessionId(sessionId)}.md`);
+	const suffix = sequence === 0 ? "" : `-${String(sequence).padStart(3, "0")}`;
+	const candidate = path.resolve(root, `${sanitizeSessionId(sessionId)}${suffix}.md`);
 	if (path.dirname(candidate) !== root) throw new Error("Generated plan path escaped the plans directory");
 	return candidate;
 }