From 6b7b290405a2de474fe7d134736fb58eac8e8298 Mon Sep 17 00:00:00 2001 From: Aleksandr Ponimaskin Date: Tue, 8 Sep 2026 13:23:07 +0200 Subject: [PATCH] Align tool, command, and flag names with plannotator `@plannotator/pi-extension` ships an overlapping pi plan mode. Adopt its naming convention so the two are distinguishable, and match its write gate and review-outcome model where revdiff can express it. Renames: - `plan_submit` -> `revdiff_submit_plan` - `mark_done` -> `revdiff_mark_done` - `/plan` -> `/revdiff-plan-mode` - `/plan-abort` -> `/revdiff-plan-abort` - `/plan-status` -> `/revdiff-plan-status` - `--plan` -> `--revdiff-plan`, avoiding a collision with plannotator's own `--plan` flag Add `stripPlanTools`, which filters the pre-rename names alongside the current ones so a session persisted by an earlier version cannot carry a stale `plan_submit` into a restored tool list. Drop the `isAbsolute` early return from `isPlanPathAllowed` to match plannotator's `isPlanWritePathAllowed`: an absolute path is now judged by containment, so one pointing inside cwd is allowed. Add a third review outcome. revdiff exposes two signals only, exit 0 for a clean quit and exit 10 for annotations, so a crash, a signal, or a missing binary previously reached the agent as fabricated plan feedback and invited it to revise the plan in response to an error. Classification moves into an exported pure `classifyReviewOutcome`, and a session that ended without a decision now tells the agent to resubmit instead. Approve-with-notes is deliberately not implemented: revdiff has no signal that distinguishes annotating-and-approving from annotating-and-denying. --- index.ts | 288 ++++++++++++++++++++++++++++++++----------- readme.md | 34 +++-- test/parsing.test.ts | 75 ++++++++--- test/state.test.ts | 62 ++++++++-- 4 files changed, 350 insertions(+), 109 deletions(-) diff --git a/index.ts b/index.ts index b21d7ae..997751c 100644 --- a/index.ts +++ b/index.ts @@ -6,7 +6,7 @@ * During planning: * - Agent explores codebase, writes a markdown plan file * - Writes/edits restricted to .md/.mdx files inside cwd - * - Agent calls plan_submit(filePath) to request review + * - Agent calls revdiff_submit_plan(filePath) to request review * - revdiff opens with --only=; user annotates or quits clean * - No annotations → approved → transition to executing * - Annotations → feedback returned to agent → agent revises → resubmit @@ -16,7 +16,13 @@ * - Checklist progress tracked via [DONE:n] markers in agent responses */ -import { existsSync, mkdtempSync, readFileSync, rmSync, statSync } from "node:fs"; +import { + existsSync, + mkdtempSync, + readFileSync, + rmSync, + statSync, +} from "node:fs"; import { tmpdir } from "node:os"; import * as path from "node:path"; import { spawnSync } from "node:child_process"; @@ -31,8 +37,11 @@ import type { export const STATE_ENTRY_TYPE = "revdiff-plan-state"; export const EXECUTE_ENTRY_TYPE = "revdiff-plan-execute"; const EXIT_CODE_ANNOTATIONS = 10; -export const PLAN_SUBMIT_TOOL = "plan_submit"; -const MARK_DONE_TOOL = "mark_done"; +export const PLAN_SUBMIT_TOOL = "revdiff_submit_plan"; +const MARK_DONE_TOOL = "revdiff_mark_done"; +// Tool names used before the plannotator-aligned rename. Sessions persisted +// under the old names must not carry a stale tool into a restored tool list. +const LEGACY_PLAN_TOOLS = ["plan_submit", "mark_done"]; const ALLOWED_EXTENSIONS = new Set([".md", ".mdx"]); // ── Types ──────────────────────────────────────────────────────────────────── @@ -65,9 +74,51 @@ interface ClearedState { // ── Helpers ────────────────────────────────────────────────────────────────── +function stripPlanTools(tools: readonly string[]): string[] { + return tools.filter( + (t) => + t !== PLAN_SUBMIT_TOOL && + t !== MARK_DONE_TOOL && + !LEGACY_PLAN_TOOLS.includes(t), + ); +} + +export interface ReviewOutcome { + outcome: "approved" | "feedback" | "closed"; + annotations: string; +} + +// revdiff exposes two signals only: exit 0 (clean quit) and exit 10 +// (annotations produced). Anything else means the session ended without a +// decision, which is its own outcome rather than feedback on the plan. +export function classifyReviewOutcome( + launchError: string, + exitCode: number | null, + rawOutput: string, +): ReviewOutcome { + if (launchError) { + return { + outcome: "closed", + annotations: `failed to launch revdiff: ${launchError}`, + }; + } + if ( + typeof exitCode !== "number" || + (exitCode !== 0 && exitCode !== EXIT_CODE_ANNOTATIONS) + ) { + return { + outcome: "closed", + annotations: `revdiff exited with code ${exitCode ?? "unknown"}`, + }; + } + if (!rawOutput) { + return { outcome: "approved", annotations: "" }; + } + return { outcome: "feedback", annotations: rawOutput }; +} + export function isPlanPathAllowed(inputPath: string, cwd: string): boolean { if (!inputPath) return false; - if (path.isAbsolute(inputPath)) return false; const abs = path.resolve(cwd, inputPath); const rel = path.relative(path.resolve(cwd), abs); if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) return false; @@ -87,7 +138,10 @@ function stripCodeBlocks(text: string): string { return text.replace(/```[\s\S]*?```/g, ""); } -export function markCompletedSteps(text: string, items: ChecklistItem[]): number { +export function markCompletedSteps( + text: string, + items: ChecklistItem[], +): number { const stripped = stripCodeBlocks(text); let count = 0; for (const match of stripped.matchAll(/\[DONE:(\d+)\]/g)) { @@ -116,7 +170,8 @@ export function getAssistantText(message: unknown): string | null { typeof message !== "object" || message === null || (message as { role?: unknown }).role !== "assistant" - ) return null; + ) + return null; const content = (message as { content?: unknown }).content; if (!Array.isArray(content)) return null; const text = content @@ -136,13 +191,17 @@ export default function revdiffPlanExtension(pi: ExtensionAPI): void { let justApprovedPlan = false; // UX #10: track revision count for status bar display let submitCount = 0; - // UX #13: track last path passed to plan_submit within a planning session + // UX #13: track last path passed to revdiff_submit_plan within a planning session let lastReviewedPath: string | null = null; // ── Persistence ─────────────────────────────────────────────────────── function persistState(): void { - pi.appendEntry(STATE_ENTRY_TYPE, { phase, lastSubmittedPath, savedTools } satisfies PersistedState); + pi.appendEntry(STATE_ENTRY_TYPE, { + phase, + lastSubmittedPath, + savedTools, + } satisfies PersistedState); } // ── Status / Widget ─────────────────────────────────────────────────── @@ -157,7 +216,10 @@ export default function revdiffPlanExtension(pi: ExtensionAPI): void { if (phase === "executing") { if (checklistItems.length > 0) { const done = checklistItems.filter((t) => t.completed).length; - ctx.ui.setStatus("revdiff-plan", ctx.ui.theme.fg("accent", `📋 ${done}/${checklistItems.length}`)); + ctx.ui.setStatus( + "revdiff-plan", + ctx.ui.theme.fg("accent", `📋 ${done}/${checklistItems.length}`), + ); } else { ctx.ui.setStatus("revdiff-plan", ctx.ui.theme.fg("accent", "▶ exec")); } @@ -191,10 +253,13 @@ export default function revdiffPlanExtension(pi: ExtensionAPI): void { submitCount = 0; lastReviewedPath = null; savedTools = pi.getActiveTools(); - pi.setActiveTools([...savedTools, PLAN_SUBMIT_TOOL]); + pi.setActiveTools([...stripPlanTools(savedTools), PLAN_SUBMIT_TOOL]); persistState(); updateStatus(ctx); - ctx.ui.notify("Plan mode enabled. Agent will explore and write a plan file.", "info"); + ctx.ui.notify( + "Plan mode enabled. Agent will explore and write a plan file.", + "info", + ); } // Fix #2: append ClearedState so restoreState treats this session branch as a fresh start @@ -204,7 +269,9 @@ export default function revdiffPlanExtension(pi: ExtensionAPI): void { lastSubmittedPath = null; submitCount = 0; lastReviewedPath = null; - pi.setActiveTools((savedTools.length > 0 ? savedTools : pi.getActiveTools().filter((t) => t !== PLAN_SUBMIT_TOOL)).filter((t) => t !== MARK_DONE_TOOL)); + pi.setActiveTools( + stripPlanTools(savedTools.length > 0 ? savedTools : pi.getActiveTools()), + ); savedTools = []; pi.appendEntry(STATE_ENTRY_TYPE, { cleared: true } satisfies ClearedState); updateStatus(ctx); @@ -219,9 +286,9 @@ export default function revdiffPlanExtension(pi: ExtensionAPI): void { } else if (phase === "planning") { exitToIdle(ctx); } else { - // executing — require an explicit /plan-abort to prevent accidental data loss + // executing — require an explicit /revdiff-plan-abort to prevent accidental data loss ctx.ui.notify( - "Cannot toggle plan mode during execution. Use /plan-abort to cancel and return to idle.", + "Cannot toggle plan mode during execution. Use /revdiff-plan-abort to cancel and return to idle.", "warning", ); } @@ -237,7 +304,10 @@ export default function revdiffPlanExtension(pi: ExtensionAPI): void { lastSubmittedPath = inputPath; checklistItems = parseChecklist(planContent); phase = "executing"; - pi.setActiveTools([...(savedTools.length > 0 ? savedTools : pi.getActiveTools().filter((t) => t !== PLAN_SUBMIT_TOOL)), MARK_DONE_TOOL]); + pi.setActiveTools([ + ...stripPlanTools(savedTools.length > 0 ? savedTools : pi.getActiveTools()), + MARK_DONE_TOOL, + ]); pi.appendEntry(EXECUTE_ENTRY_TYPE, { lastSubmittedPath }); persistState(); justApprovedPlan = true; @@ -249,7 +319,9 @@ export default function revdiffPlanExtension(pi: ExtensionAPI): void { "info", ); return { - content: [{ type: "text" as const, text: pathNote + buildApprovedPrompt(inputPath) }], + content: [ + { type: "text" as const, text: pathNote + buildApprovedPrompt(inputPath) }, + ], details: { approved: true }, terminate: true, }; @@ -260,10 +332,14 @@ export default function revdiffPlanExtension(pi: ExtensionAPI): void { async function reviewPlanWithRevdiff( ctx: ExtensionContext, planPath: string, - ): Promise<{ approved: boolean; annotations: string }> { + ): Promise { const revdiffBin = resolveRevdiffBin(); if (!revdiffBin) { - return { approved: false, annotations: "Error: revdiff binary not found. Install it with: brew install umputun/apps/revdiff" }; + return { + outcome: "closed", + annotations: + "revdiff binary not found. Install it with: brew install umputun/apps/revdiff", + }; } const tempDir = mkdtempSync(path.join(tmpdir(), "revdiff-plan-")); @@ -292,25 +368,21 @@ export default function revdiffPlanExtension(pi: ExtensionAPI): void { done(result.status ?? (result.error ? 1 : 0)); return { render: () => [], invalidate() {} }; }); - rawOutput = existsSync(outputFile) ? readFileSync(outputFile, "utf8").trim() : ""; + rawOutput = existsSync(outputFile) + ? readFileSync(outputFile, "utf8").trim() + : ""; } finally { - try { rmSync(tempDir, { recursive: true, force: true }); } catch { /* ignore */ } - } - - if (launchError) { - return { approved: false, annotations: `Error launching revdiff: ${launchError}` }; - } - if (typeof exitCode !== "number" || (exitCode !== 0 && exitCode !== EXIT_CODE_ANNOTATIONS)) { - return { approved: false, annotations: `revdiff exited with code ${exitCode ?? "unknown"}` }; + try { + rmSync(tempDir, { recursive: true, force: true }); + } catch { + /* ignore */ + } } - if (!rawOutput) { - return { approved: true, annotations: "" }; - } - return { approved: false, annotations: rawOutput }; + return classifyReviewOutcome(launchError, exitCode, rawOutput); } - // ── plan_submit tool ────────────────────────────────────────────────── + // ── revdiff_submit_plan tool ────────────────────────────────────────── pi.registerTool({ name: PLAN_SUBMIT_TOOL, @@ -320,7 +392,7 @@ export default function revdiffPlanExtension(pi: ExtensionAPI): void { "Call this only while plan mode is active, after writing your plan as a markdown file inside the working directory. " + "Pass the path to the plan file (e.g. PLAN.md or plans/feature.md). " + "The user reviews the plan in revdiff and can approve (quit clean) or annotate lines with feedback. " + - "If feedback is returned, revise the plan in-place and call plan_submit again.", + "If feedback is returned, revise the plan in-place and call revdiff_submit_plan again.", parameters: Type.Object({ filePath: Type.String({ description: @@ -330,12 +402,16 @@ export default function revdiffPlanExtension(pi: ExtensionAPI): void { async execute(_toolCallId, params, _signal, _onUpdate, ctx) { if (phase !== "planning") { - return toolText("Error: Not in plan mode. Use /plan to enter planning mode first."); + return toolText( + "Error: Not in plan mode. Use /revdiff-plan-mode to enter planning mode first.", + ); } const inputPath = (params as { filePath?: string })?.filePath?.trim() ?? ""; if (!inputPath) { - return toolText(`Error: ${PLAN_SUBMIT_TOOL} requires a filePath argument (e.g. "PLAN.md").`); + return toolText( + `Error: ${PLAN_SUBMIT_TOOL} requires a filePath argument (e.g. "PLAN.md").`, + ); } if (!isPlanPathAllowed(inputPath, ctx.cwd)) { @@ -348,10 +424,14 @@ export default function revdiffPlanExtension(pi: ExtensionAPI): void { try { if (!statSync(fullPath).isFile()) { - return toolText(`Error: ${inputPath} is not a regular file. Write your plan first.`); + return toolText( + `Error: ${inputPath} is not a regular file. Write your plan first.`, + ); } } catch { - return toolText(`Error: ${inputPath} does not exist. Write your plan using the write tool first.`); + return toolText( + `Error: ${inputPath} does not exist. Write your plan using the write tool first.`, + ); } const planContent = readFileSync(fullPath, "utf8"); @@ -375,12 +455,25 @@ export default function revdiffPlanExtension(pi: ExtensionAPI): void { return transitionToExecuting(ctx, inputPath, planContent, pathNote); } - const { approved, annotations } = await reviewPlanWithRevdiff(ctx, fullPath); + const { outcome, annotations } = await reviewPlanWithRevdiff(ctx, fullPath); - if (approved) { + if (outcome === "approved") { return transitionToExecuting(ctx, inputPath, planContent, pathNote); } + if (outcome === "closed") { + // No decision was made — must not reach the agent as plan feedback. + return { + content: [ + { + type: "text" as const, + text: buildClosedPrompt(inputPath, annotations), + }, + ], + details: { approved: false }, + }; + } + // Feedback — stay in planning return { content: [ @@ -397,7 +490,8 @@ export default function revdiffPlanExtension(pi: ExtensionAPI): void { pi.registerTool({ name: MARK_DONE_TOOL, label: "Mark Step Done", - description: "Mark a plan step as completed. Call this after finishing each step, before starting the next one.", + description: + "Mark a plan step as completed. Call this after finishing each step, before starting the next one.", parameters: Type.Object({ index: Type.Number({ description: "Zero-based index of the completed step.", @@ -409,7 +503,9 @@ export default function revdiffPlanExtension(pi: ExtensionAPI): void { } const { index } = params as { index: number }; if (index < 0 || index >= checklistItems.length) { - return toolText(`Error: index ${index} out of range (0–${checklistItems.length - 1}).`); + return toolText( + `Error: index ${index} out of range (0–${checklistItems.length - 1}).`, + ); } if (checklistItems[index]!.completed) { return toolText(`Step ${index} already marked done.`); @@ -419,7 +515,9 @@ export default function revdiffPlanExtension(pi: ExtensionAPI): void { updateWidget(ctx); persistState(); const done = checklistItems.filter((t) => t.completed).length; - return toolText(`Step ${index} done. Progress: ${done}/${checklistItems.length}`); + return toolText( + `Step ${index} done. Progress: ${done}/${checklistItems.length}`, + ); }, }); @@ -452,13 +550,13 @@ export default function revdiffPlanExtension(pi: ExtensionAPI): void { .map(({ t, i }) => `${i}. ${t.text}`) .join("\n"); return { - systemPrompt: `[EXECUTING]\nWork through the remaining steps in order. After completing each step, call mark_done(index) with its zero-based index before starting the next step.\n\nRemaining steps:\n${remaining}`, + systemPrompt: `[EXECUTING]\nWork through the remaining steps in order. After completing each step, call ${MARK_DONE_TOOL}(index) with its zero-based index before starting the next step.\n\nRemaining steps:\n${remaining}`, }; } }); // Safety net for session restore: scan [DONE:N] markers in finalized messages. - // During normal execution mark_done tool handles progress tracking. + // During normal execution revdiff_mark_done tool handles progress tracking. pi.on("message_end", async (event, ctx) => { if (phase !== "executing" || checklistItems.length === 0) return; const text = getAssistantText(event.message); @@ -482,7 +580,9 @@ export default function revdiffPlanExtension(pi: ExtensionAPI): void { if (phase !== "executing" || checklistItems.length === 0) return; if (!checklistItems.every((t) => t.completed)) return; - const completedList = checklistItems.map((t) => `- [x] ~~${t.text}~~`).join("\n"); + const completedList = checklistItems + .map((t) => `- [x] ~~${t.text}~~`) + .join("\n"); pi.sendMessage( { customType: "revdiff-plan-complete", @@ -497,7 +597,7 @@ export default function revdiffPlanExtension(pi: ExtensionAPI): void { // Restore persisted state on session start/resume pi.on("session_start", async (_event, ctx) => { - if (pi.getFlag("plan") === true && phase === "idle") { + if (pi.getFlag("revdiff-plan") === true && phase === "idle") { enterPlanning(ctx); return; } @@ -523,8 +623,8 @@ export default function revdiffPlanExtension(pi: ExtensionAPI): void { } if (!restored) { - // Ensure plan_submit and mark_done are not in tool list on fresh/cleared sessions - pi.setActiveTools(pi.getActiveTools().filter((t) => t !== PLAN_SUBMIT_TOOL && t !== MARK_DONE_TOOL)); + // Ensure plan/execute tools are not in tool list on fresh/cleared sessions + pi.setActiveTools(stripPlanTools(pi.getActiveTools())); return; } @@ -534,8 +634,14 @@ export default function revdiffPlanExtension(pi: ExtensionAPI): void { if (phase === "executing") { // Re-load checklist from disk + scan session messages for [DONE:n] - if (lastSubmittedPath && existsSync(path.resolve(ctx.cwd, lastSubmittedPath))) { - const content = readFileSync(path.resolve(ctx.cwd, lastSubmittedPath), "utf8"); + if ( + lastSubmittedPath && + existsSync(path.resolve(ctx.cwd, lastSubmittedPath)) + ) { + const content = readFileSync( + path.resolve(ctx.cwd, lastSubmittedPath), + "utf8", + ); checklistItems = parseChecklist(content); // Find execute marker, then scan subsequent messages @@ -557,9 +663,11 @@ export default function revdiffPlanExtension(pi: ExtensionAPI): void { if (text) markCompletedSteps(text, checklistItems); } } - // Fix #1: reinstate the saved tool list for the executing phase, with mark_done added - const baseTools = savedTools.length > 0 ? savedTools : pi.getActiveTools().filter((t) => t !== PLAN_SUBMIT_TOOL && t !== MARK_DONE_TOOL); - pi.setActiveTools([...baseTools.filter((t) => t !== MARK_DONE_TOOL), MARK_DONE_TOOL]); + // Fix #1: reinstate the saved tool list for the executing phase, with the mark-done tool added + const baseTools = stripPlanTools( + savedTools.length > 0 ? savedTools : pi.getActiveTools(), + ); + pi.setActiveTools([...baseTools, MARK_DONE_TOOL]); } else { // Plan file gone, fall back to idle phase = "idle"; @@ -568,7 +676,13 @@ export default function revdiffPlanExtension(pi: ExtensionAPI): void { } if (phase === "planning") { - pi.setActiveTools([...new Set([...pi.getActiveTools().filter((t) => t !== PLAN_SUBMIT_TOOL), ...savedTools, PLAN_SUBMIT_TOOL])]); + pi.setActiveTools([ + ...new Set([ + ...stripPlanTools(pi.getActiveTools()), + ...stripPlanTools(savedTools), + PLAN_SUBMIT_TOOL, + ]), + ]); } updateStatus(ctx); @@ -577,22 +691,23 @@ export default function revdiffPlanExtension(pi: ExtensionAPI): void { // ── Commands ────────────────────────────────────────────────────────── - pi.registerCommand("plan", { - description: "Toggle plan mode: idle → planning, planning → idle (use /plan-abort to cancel execution)", + pi.registerCommand("revdiff-plan-mode", { + description: + "Toggle plan mode: idle → planning, planning → idle (use /revdiff-plan-abort to cancel execution)", handler: async (_args, ctx) => { togglePlanMode(ctx); }, }); // Fix #8: dedicated abort command so execution can't be cancelled by accident - pi.registerCommand("plan-abort", { + pi.registerCommand("revdiff-plan-abort", { description: "Cancel plan execution and return to idle", handler: async (_args, ctx) => { if (phase !== "executing") { ctx.ui.notify( phase === "idle" - ? "Not in plan mode. Use /plan to start." - : "Use /plan to toggle planning mode.", + ? "Not in plan mode. Use /revdiff-plan-mode to start." + : "Use /revdiff-plan-mode to toggle planning mode.", "info", ); return; @@ -601,7 +716,7 @@ export default function revdiffPlanExtension(pi: ExtensionAPI): void { }, }); - pi.registerCommand("plan-status", { + pi.registerCommand("revdiff-plan-status", { description: "Show current plan mode phase and progress", handler: async (_args, ctx) => { const parts = [`Phase: ${phase}`]; @@ -620,7 +735,7 @@ export default function revdiffPlanExtension(pi: ExtensionAPI): void { // ── Flag ────────────────────────────────────────────────────────────── - pi.registerFlag("plan", { + pi.registerFlag("revdiff-plan", { description: "Start in plan mode", type: "boolean", default: false, @@ -649,7 +764,7 @@ export function restoreState( } if (!restored) { - pi.setActiveTools(pi.getActiveTools().filter((t) => t !== PLAN_SUBMIT_TOOL && t !== MARK_DONE_TOOL)); + pi.setActiveTools(stripPlanTools(pi.getActiveTools())); return; } @@ -658,8 +773,14 @@ export function restoreState( state.savedTools = restored.savedTools; if (state.phase === "executing") { - if (state.lastSubmittedPath && existsSync(path.resolve(ctx.cwd, state.lastSubmittedPath))) { - const content = readFileSync(path.resolve(ctx.cwd, state.lastSubmittedPath), "utf8"); + if ( + state.lastSubmittedPath && + existsSync(path.resolve(ctx.cwd, state.lastSubmittedPath)) + ) { + const content = readFileSync( + path.resolve(ctx.cwd, state.lastSubmittedPath), + "utf8", + ); state.checklistItems = parseChecklist(content); let execIdx = -1; @@ -680,8 +801,10 @@ export function restoreState( if (text) markCompletedSteps(text, state.checklistItems); } } - const baseTools = state.savedTools.length > 0 ? state.savedTools : pi.getActiveTools().filter((t) => t !== PLAN_SUBMIT_TOOL && t !== MARK_DONE_TOOL); - pi.setActiveTools([...baseTools.filter((t) => t !== MARK_DONE_TOOL)]); + const baseTools = stripPlanTools( + state.savedTools.length > 0 ? state.savedTools : pi.getActiveTools(), + ); + pi.setActiveTools([...baseTools]); onUpdated(); } else { state.phase = "idle"; @@ -690,7 +813,13 @@ export function restoreState( } if (state.phase === "planning") { - pi.setActiveTools([...new Set([...pi.getActiveTools().filter((t) => t !== PLAN_SUBMIT_TOOL), ...state.savedTools, PLAN_SUBMIT_TOOL])]); + pi.setActiveTools([ + ...new Set([ + ...stripPlanTools(pi.getActiveTools()), + ...stripPlanTools(state.savedTools), + PLAN_SUBMIT_TOOL, + ]), + ]); onUpdated(); } } @@ -707,7 +836,11 @@ function isPersistedState(data: unknown): data is PersistedState { } function isClearedState(data: unknown): data is ClearedState { - return typeof data === "object" && data !== null && (data as ClearedState).cleared === true; + return ( + typeof data === "object" && + data !== null && + (data as ClearedState).cleared === true + ); } // ── Prompt strings ──────────────────────────────────────────────────────────── @@ -725,7 +858,11 @@ function buildApprovedPrompt(filePath: string): string { ].join("\n\n"); } -function buildDeniedPrompt(filePath: string, annotations: string, pathNote: string): string { +function buildDeniedPrompt( + filePath: string, + annotations: string, + pathNote: string, +): string { return [ `${pathNote}The user reviewed "${filePath}" and left the following feedback:`, annotations, @@ -733,12 +870,19 @@ function buildDeniedPrompt(filePath: string, annotations: string, pathNote: stri ].join("\n\n"); } +function buildClosedPrompt(filePath: string, reason: string): string { + return [ + `The revdiff review session for "${filePath}" was closed before a decision was made: ${reason}.`, + `The plan was neither approved nor rejected; call ${PLAN_SUBMIT_TOOL} again to reopen review.`, + ].join("\n\n"); +} + const PLANNING_PROMPT = `[PLAN MODE] You are in plan mode. You MUST NOT make any changes to the codebase — no edits, commits, installs, or destructive commands. During planning you may only write or edit markdown files (.md, .mdx) inside the working directory. ## Your goal -Explore the codebase, understand the task, write a plan file, then call plan_submit to submit it for review. +Explore the codebase, understand the task, write a plan file, then call revdiff_submit_plan to submit it for review. ## Plan file structure @@ -755,6 +899,6 @@ Use a clear markdown file (e.g. PLAN.md) with: 1. Explore with read, bash, grep, find, ls — understand what exists before proposing 2. Write a skeleton plan early, refine as you learn more 3. Ask the user if you hit ambiguities only they can answer -4. Call plan_submit when the plan is ready +4. Call revdiff_submit_plan when the plan is ready Keep it concise. Use write for the first draft, edit for all revisions.`; diff --git a/readme.md b/readme.md index 987ad26..11cb016 100644 --- a/readme.md +++ b/readme.md @@ -12,9 +12,9 @@ This extension adds a lightweight state machine to Pi: The review loop is simple: -1. Start plan mode with `/plan` +1. Start plan mode with `/revdiff-plan-mode` 2. Let the agent explore and write a markdown plan -3. The agent calls `plan_submit("PLAN.md")` +3. The agent calls `revdiff_submit_plan("PLAN.md")` 4. `revdiff` opens for review 5. If you quit with no annotations, the plan is approved 6. If you annotate lines, the feedback goes back to the agent for revision @@ -26,9 +26,11 @@ The review loop is simple: - [Pi coding agent](https://github.com/earendil-works/pi-coding-agent) - [revdiff](https://github.com/umputun/revdiff) available in `PATH` - macOS/Homebrew example: + ```bash brew install umputun/apps/revdiff ``` + - A terminal environment where Pi can launch TUI tools ## Install @@ -62,15 +64,15 @@ pi ### Start directly in plan mode ```bash -pi --plan +pi --revdiff-plan ``` ### Typical session ```text -/plan +/revdiff-plan-mode # agent explores codebase and writes PLAN.md -# agent calls plan_submit("PLAN.md") +# agent calls revdiff_submit_plan("PLAN.md") # revdiff opens for review # annotate and quit, or quit clean to approve ``` @@ -79,19 +81,19 @@ After approval, the extension restores the previously active tool set and tracks ## Commands -### `/plan` +### `/revdiff-plan-mode` Toggles plan mode when safe: - `idle` → `planning` - `planning` → `idle` -- during `executing`, it does not abort silently; it warns you to use `/plan-abort` +- during `executing`, it does not abort silently; it warns you to use `/revdiff-plan-abort` -### `/plan-abort` +### `/revdiff-plan-abort` Cancels the current execution phase and returns to idle mode. -### `/plan-status` +### `/revdiff-plan-status` Shows: @@ -102,14 +104,14 @@ Shows: ## Flags -### `--plan` +### `--revdiff-plan` Starts Pi with plan mode enabled. Example: ```bash -pi --plan +pi --revdiff-plan ``` ## How plan files should look @@ -187,6 +189,16 @@ Examples of rejected paths: - `/absolute/path/outside/repo.md` - `plan.txt` +An absolute path is judged by containment, so one that points inside the working +directory (for example `/repo/PLAN.md` while working in `/repo`) is accepted. + +### The review closed without a decision + +If `revdiff` cannot launch, or exits with anything other than its clean-quit (`0`) +or annotations (`10`) codes, the plan is neither approved nor rejected. The agent +is told to call `revdiff_submit_plan` again rather than treating the failure as +plan feedback. + ### The agent cannot edit source files in plan mode That is expected. During planning, `write` and `edit` are restricted to markdown files only. Approve the plan first to restore full tool access. diff --git a/test/parsing.test.ts b/test/parsing.test.ts index dffb78c..d0ac3f1 100644 --- a/test/parsing.test.ts +++ b/test/parsing.test.ts @@ -1,14 +1,22 @@ import test from "node:test"; import assert from "node:assert/strict"; -import { getAssistantText, isPlanPathAllowed, markCompletedSteps, parseChecklist } from "../index.js"; +import { + classifyReviewOutcome, + getAssistantText, + isPlanPathAllowed, + markCompletedSteps, + parseChecklist, +} from "../index.js"; test("parseChecklist parses unchecked, checked, and DONE markers", () => { - const items = parseChecklist([ - "- [ ] first", - "- [x] second", - "- [DONE:2] third", - "not a checklist item", - ].join("\n")); + const items = parseChecklist( + [ + "- [ ] first", + "- [x] second", + "- [DONE:2] third", + "not a checklist item", + ].join("\n"), + ); assert.deepEqual(items, [ { text: "first", completed: false }, @@ -27,14 +35,17 @@ test("markCompletedSteps matches inline markers and ignores code blocks", () => // [DONE:1] is on its own line — should fire // [DONE:2] is inside a fenced code block — should NOT fire // [DONE:0] is inline at end of sentence — should fire - const count = markCompletedSteps([ - "Finished work.", - "[DONE:1]", - "```ts", - "const marker = '[DONE:2]';", - "```", - "Updated the readme. [DONE:0]", - ].join("\n"), items); + const count = markCompletedSteps( + [ + "Finished work.", + "[DONE:1]", + "```ts", + "const marker = '[DONE:2]';", + "```", + "Updated the readme. [DONE:0]", + ].join("\n"), + items, + ); assert.equal(count, 2); assert.deepEqual(items, [ @@ -45,9 +56,7 @@ test("markCompletedSteps matches inline markers and ignores code blocks", () => }); test("markCompletedSteps ignores markers inside fenced code blocks", () => { - const items = [ - { text: "only item", completed: false }, - ]; + const items = [{ text: "only item", completed: false }]; const count = markCompletedSteps( "Here is an example:\n```\n[DONE:0]\n```\nDone!", @@ -65,7 +74,35 @@ test("isPlanPathAllowed requires markdown within cwd", () => { assert.equal(isPlanPathAllowed("README.txt", cwd), false); assert.equal(isPlanPathAllowed("../escape.md", cwd), false); assert.equal(isPlanPathAllowed("", cwd), false); - assert.equal(isPlanPathAllowed("/repo/PLAN.md", cwd), false); + // Matches plannotator's isPlanWritePathAllowed: an absolute path is judged by + // containment, so one pointing inside cwd is allowed. + assert.equal(isPlanPathAllowed("/repo/PLAN.md", cwd), true); + assert.equal(isPlanPathAllowed("/elsewhere/PLAN.md", cwd), false); +}); + +test("classifyReviewOutcome maps revdiff's two exit signals", () => { + assert.deepEqual(classifyReviewOutcome("", 0, ""), { + outcome: "approved", + annotations: "", + }); + assert.deepEqual(classifyReviewOutcome("", 10, "line 3: rethink this"), { + outcome: "feedback", + annotations: "line 3: rethink this", + }); +}); + +test("classifyReviewOutcome reports a session that ended without a decision", () => { + // A crash, a signal, or a missing binary is not plan feedback: the agent must + // not try to revise the plan in response to it. + for (const exitCode of [1, 130, null]) { + const result = classifyReviewOutcome("", exitCode, ""); + assert.equal(result.outcome, "closed", `exit ${exitCode} should be closed`); + } + + assert.equal( + classifyReviewOutcome("spawn ENOENT", null, "").outcome, + "closed", + ); }); test("getAssistantText extracts text blocks from assistant message", () => { diff --git a/test/state.test.ts b/test/state.test.ts index 38f5497..08fbaaa 100644 --- a/test/state.test.ts +++ b/test/state.test.ts @@ -3,7 +3,13 @@ import assert from "node:assert/strict"; import { mkdtempSync, writeFileSync, rmSync } from "node:fs"; import { tmpdir } from "node:os"; import * as path from "node:path"; -import { restoreState, type RuntimeState, EXECUTE_ENTRY_TYPE, PLAN_SUBMIT_TOOL, STATE_ENTRY_TYPE } from "../index.js"; +import { + restoreState, + type RuntimeState, + EXECUTE_ENTRY_TYPE, + PLAN_SUBMIT_TOOL, + STATE_ENTRY_TYPE, +} from "../index.js"; function createState(): RuntimeState { return { @@ -37,12 +43,23 @@ test("restoreState restores executing checklist progress and active tools", () = { type: "custom", customType: STATE_ENTRY_TYPE, - data: { phase: "executing", lastSubmittedPath: "PLAN.md", savedTools: ["read", "bash"] }, + data: { + phase: "executing", + lastSubmittedPath: "PLAN.md", + savedTools: ["read", "bash"], + }, + }, + { + type: "custom", + customType: EXECUTE_ENTRY_TYPE, + data: { lastSubmittedPath: "PLAN.md" }, }, - { type: "custom", customType: EXECUTE_ENTRY_TYPE, data: { lastSubmittedPath: "PLAN.md" } }, { type: "message", - message: { role: "assistant", content: [{ type: "text", text: "Done\n[DONE:1]" }] }, + message: { + role: "assistant", + content: [{ type: "text", text: "Done\n[DONE:1]" }], + }, }, ]; const pi = createPi(); @@ -70,7 +87,7 @@ test("restoreState restores executing checklist progress and active tools", () = } }); -test("restoreState honors cleared state and removes plan_submit", () => { +test("restoreState honors cleared state and removes the plan-submit tool", () => { const pi = createPi(["read", PLAN_SUBMIT_TOOL, "write"]); const state = createState(); const entries = [ @@ -101,14 +118,18 @@ test("restoreState honors cleared state and removes plan_submit", () => { assert.equal(updated, 0); }); -test("restoreState restores planning tools including plan_submit", () => { +test("restoreState restores planning tools including the plan-submit tool", () => { const pi = createPi(["read", "bash"]); const state = createState(); const entries = [ { type: "custom", customType: STATE_ENTRY_TYPE, - data: { phase: "planning", lastSubmittedPath: null, savedTools: ["read", "bash"] }, + data: { + phase: "planning", + lastSubmittedPath: null, + savedTools: ["read", "bash"], + }, }, ]; @@ -126,3 +147,30 @@ test("restoreState restores planning tools including plan_submit", () => { assert.deepEqual(pi.getActiveTools(), ["read", "bash", PLAN_SUBMIT_TOOL]); assert.equal(updated, 1); }); + +test("restoreState strips tool names persisted before the rename", () => { + // Sessions saved by an earlier version carry the old names; they must not + // survive into a restored tool list alongside the current ones. + const pi = createPi(["read", "plan_submit", "mark_done", "write"]); + const state = createState(); + const entries = [ + { + type: "custom", + customType: STATE_ENTRY_TYPE, + data: { + phase: "planning", + lastSubmittedPath: null, + savedTools: ["read", "plan_submit", "write"], + }, + }, + ]; + + restoreState( + pi as never, + { cwd: "/repo", sessionManager: { getBranch: () => entries } } as never, + state, + () => {}, + ); + + assert.deepEqual(pi.getActiveTools(), ["read", "write", PLAN_SUBMIT_TOOL]); +});