@gavin-hu/my-pi-agent 0.17.0 → 0.18.0

package/extensions/plan/plans.ts

@@ -4,15 +4,19 @@
  * A plan is written to disk as markdown: one file per plan, named from the
  * title and stamp. A refinement rewrites that file atomically, so the user can
  * read the same artifact the model is working from and the plan survives
- * outside the conversation without a partial write ever being visible. Files
- * live under `<repo-root>/.pi/plans` (the worktree root inside a worktree), or
- * under `<agent-dir>/plans` outside a repository. An extension tool sees the
- * session cwd rather than the worktree the user entered, so the active worktree
- * is applied before any path is resolved.
+ * outside the conversation without a partial write ever being visible.
  *
- * The directory is self-ignoring: the first write drops a `.gitignore` with `*`
- * so plans never show up as untracked files or inside rewind snapshots,
- * without editing the project's own `.gitignore`.
+ * Plans live under `<agent-dir>/plans/<repo-key>`, keyed by the repository's
+ * common git directory, so every worktree and every session of one repository
+ * reads one store — a plan approved in a worktree is the same plan from the main
+ * checkout. Outside a repository they land under `<agent-dir>/plans`. An
+ * extension tool sees the session cwd rather than the worktree the user entered,
+ * so the active worktree is applied before any path is resolved.
+ *
+ * Plans are outside the project, so they are never untracked files and never
+ * appear in a rewind snapshot. A store written by an older version, under
+ * `<repo>/.pi/plans`, is moved in once, and nothing is deleted before its plans
+ * have arrived.
  *
  * This module owns paths and bytes only; tool wiring lives in `tools.ts`.
  */
@@ -25,17 +29,20 @@ import {
 	readFileSync,
 	readdirSync,
 	renameSync,
+	rmdirSync,
 	statSync,
 	unlinkSync,
 	writeFileSync,
 } from "node:fs";
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { CONFIG_DIR_NAME, getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { resolveEffectiveCwd } from "../../lib/env.ts";
-import { repoRootFor } from "../../lib/git/index.ts";
-import { sanitizeLine } from "../../lib/format.ts";
+import { sanitizeLine, shortenPath } from "../../lib/format.ts";
 import { isInside, isInsideReal } from "../../lib/path.ts";
-import { formatFeedback, type PlanAnnotation } from "./feedback.ts";
+import { plansDir } from "../../lib/plans/store.ts";
+import { repoKeyFor } from "../../lib/repo-key.ts";
+import { carryFeedback, formatFeedback, normalizeAuthor, type PlanAnnotation } from "./feedback.ts";
 import { extractPlanSteps, matchesStepText, setStepStatuses, type StepUpdate } from "./steps.ts";
 
 /** Largest plan accepted, in UTF-8 bytes. */
@@ -47,7 +54,7 @@ const MAX_SLUG_LENGTH = 60;
 export interface StoredPlan {
 	/** Absolute path. */
 	path: string;
-	/** Path relative to the working directory, when it is inside it. */
+	/** How the path is shown to the user: `~`-shortened, since plans live outside the project. */
 	relativePath: string;
 	content: string;
 	bytes: number;
@@ -62,7 +69,7 @@ export interface WrittenPlan extends StoredPlan {
 export interface PlanSummary {
 	/** Absolute path. */
 	path: string;
-	/** Path relative to the working directory, when it is inside it. */
+	/** How the path is shown to the user: `~`-shortened, since plans live outside the project. */
 	relativePath: string;
 	/** The plan's `# title`, or a title derived from the file name. */
 	title: string;
@@ -87,6 +94,13 @@ export interface WritePlanInput {
 export interface PlanStore {
 	/** Directory plans are written to for `cwd`. */
 	dirFor(cwd: string): Promise<string>;
+	/**
+	 * The repository root `cwd` belongs to, or undefined outside a repository.
+	 *
+	 * A repository-scoped setting — the split switch — is read at the root, so a
+	 * session started in a subdirectory still sees what the project turned on.
+	 */
+	rootFor(cwd: string): Promise<string | undefined>;
 	write(cwd: string, input: WritePlanInput): Promise<WrittenPlan>;
 	/** Read a plan inside the plans directory, or undefined when missing/outside. */
 	read(cwd: string, planPath: string): Promise<StoredPlan | undefined>;
@@ -99,8 +113,20 @@ export interface PlanStore {
 	index(cwd: string): Promise<PlanSummary[]>;
 	/** Set the given top-level steps' checkboxes in an existing plan. Throws when the file or any step is invalid. */
 	setSteps(cwd: string, planPath: string, updates: StepUpdate[]): Promise<StoredPlan>;
-	/** Replace the plan's stored browser feedback. Throws when the file is missing or outside the plans directory. */
-	saveFeedback(cwd: string, planPath: string, annotations: PlanAnnotation[]): Promise<StoredPlan>;
+	/** Replace the comments of `options.author` (the owner when absent) and keep every other writer's. */
+	saveFeedback(
+		cwd: string,
+		planPath: string,
+		annotations: PlanAnnotation[],
+		options?: { author?: string },
+	): Promise<StoredPlan>;
+	/**
+	 * The line a one-time migration wants reported, or undefined.
+	 *
+	 * A moved store is the user's business — plans are not where they used to be —
+	 * so the first caller that can show a notice takes it and clears it.
+	 */
+	takeNotice(): string | undefined;
 }
 
 /** Timestamp prefix the plan store adds to file names. */
@@ -155,16 +181,19 @@ function isContainedPlan(dir: string, path: string): boolean {
 	return isInsideReal(dir, dirname(path));
 }
 
-/** Keep plan files out of git (and so out of rewind snapshots) without touching the project. */
-function ensureIgnored(dir: string): void {
-	const ignore = join(dir, ".gitignore");
-	try {
-		// `wx` is race-free: an existing ignore file (ours or a user's) is left alone.
-		writeFileSync(ignore, "*\n", { encoding: "utf-8", flag: "wx" });
-	} catch {
-		// A read-only plans directory will fail on the plan write anyway; the
-		// ignore file is best-effort.
-	}
+/**
+ * Resolve a `plan_path` argument against the store.
+ *
+ * A plan lives outside the project, so a path relative to the working directory
+ * can no longer name one. Absolute paths and the `~/…` form the tools display are
+ * accepted, and a bare name resolves inside the store — which is what a reader of
+ * a tool result has in hand.
+ */
+function resolvePlanArg(dir: string, planPath: string): string {
+	const text = planPath.trim();
+	if (text === "~") return homedir();
+	if (text.startsWith("~/") || text.startsWith(`~${sep}`)) return resolve(homedir(), text.slice(2));
+	return isAbsolute(text) ? resolve(text) : resolve(dir, text);
 }
 
 /**
@@ -188,12 +217,6 @@ function writeAtomic(path: string, content: string): void {
 	}
 }
 
-/** `path` relative to `cwd` when inside it, else `path`. */
-function relativeTo(cwd: string, path: string): string {
-	const rel = relative(cwd, path);
-	return rel && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel) ? rel : path;
-}
-
 function uniquePath(dir: string, base: string): string {
 	const taken = (candidate: string): boolean => {
 		try {
@@ -214,16 +237,69 @@ function uniquePath(dir: string, base: string): string {
 	return candidate;
 }
 
-/** Repository (or worktree) root of `cwd`, or undefined outside a repository. */
-async function repoRoot(pi: ExtensionAPI, cwd: string): Promise<string | undefined> {
-	// Local `rev-parse` is fast; cap it so a stuck call cannot hang the tool.
-	return repoRootFor(pi, cwd, 5_000);
+/** A repository (or worktree) root is applied before any path here is resolved. */
+
+/** How many legacy plans one migration moves, so a pathological directory cannot stall a tool call. */
+const MAX_MIGRATED_PLANS = 200;
+
+/**
+ * Move a store written by an older version, under `<repo>/.pi/plans`, into `dir`.
+ *
+ * Copy-then-unlink when a rename crosses a filesystem boundary, so a store on a
+ * different volume still arrives. Nothing here deletes before its plan has
+ * landed, a file that cannot move is left where it is, and the old directory
+ * goes only when what remains is the ignore file this package used to write.
+ */
+function migrateLegacyStore(dir: string, legacy: string): number {
+	if (!existsSync(legacy)) return 0;
+	let names: string[];
+	try {
+		names = readdirSync(legacy);
+	} catch {
+		return 0;
+	}
+	const plans = names.filter((name) => isPlanFileName(name)).slice(0, MAX_MIGRATED_PLANS);
+	let moved = 0;
+	for (const name of plans) {
+		const from = join(legacy, name);
+		try {
+			if (!statSync(from).isFile()) continue;
+			mkdirSync(dir, { recursive: true });
+			const to = uniquePath(dir, name.replace(/\.md$/i, ""));
+			try {
+				renameSync(from, to);
+			} catch {
+				writeFileSync(to, readFileSync(from), { flag: "wx" });
+				unlinkSync(from);
+			}
+			moved += 1;
+		} catch {
+			// A plan that cannot move stays where it is, and the directory stays with it.
+		}
+	}
+	try {
+		if (readdirSync(legacy).every((name) => name === ".gitignore")) {
+			const ignore = join(legacy, ".gitignore");
+			if (existsSync(ignore) && readFileSync(ignore, "utf-8") === "*\n") unlinkSync(ignore);
+			rmdirSync(legacy);
+		}
+	} catch {
+		// Leave a directory that still holds something.
+	}
+	return moved;
 }
 
 export function createPlanStore(pi: ExtensionAPI, options: { now?: () => Date } = {}): PlanStore {
 	const now = options.now ?? (() => new Date());
 	// One `git rev-parse` per effective root; a worktree switch changes that root.
-	const dirCache = new Map<string, string>();
+	const dirCache = new Map<string, { dir: string; root: string | undefined }>();
+	let notice: string | undefined;
+
+	const takeNotice = (): string | undefined => {
+		const line = notice;
+		notice = undefined;
+		return line;
+	};
 
 	/**
 	 * The root every path here is resolved against.
@@ -231,21 +307,31 @@ export function createPlanStore(pi: ExtensionAPI, options: { now?: () => Date }
 	 * A tool registered by an extension receives the session's cwd, not the
 	 * worktree the user entered: only the built-ins are re-rooted. The worktree
 	 * extension publishes its root in the environment, so this is where the two
-	 * meet, and it is applied before the git lookup, the relative path, and the
-	 * plan path resolution.
+	 * meet, and it is applied before the repository lookup, the migration of an
+	 * older store, and the plan path resolution.
 	 */
 	const baseOf = (cwd: string): string => resolveEffectiveCwd(cwd);
 
-	const dirFor = async (cwd: string): Promise<string> => {
+	const resolve = async (cwd: string): Promise<{ dir: string; root: string | undefined }> => {
 		const base = baseOf(cwd);
 		const cached = dirCache.get(base);
 		if (cached) return cached;
-		const root = await repoRoot(pi, base);
-		const dir = root ? join(root, CONFIG_DIR_NAME, "plans") : join(getAgentDir(), "plans");
-		dirCache.set(base, dir);
-		return dir;
+		const repo = await repoKeyFor(pi, base);
+		const dir = plansDir(getAgentDir(), repo.fromGit ? repo.key : undefined);
+		dirCache.set(base, { dir, root: repo.fromGit ? repo.root : undefined });
+		if (repo.fromGit) {
+			// The keyed directory is the store; a store an older version left in the
+			// checkout moves in once, so an upgrade does not strand its plans.
+			const moved = migrateLegacyStore(dir, join(base, CONFIG_DIR_NAME, "plans"));
+			if (moved > 0) notice = `Moved ${moved} plan${moved === 1 ? "" : "s"} to ${shortenPath(dir)}.`;
+		}
+		return { dir, root: repo.fromGit ? repo.root : undefined };
 	};
 
+	const dirFor = async (cwd: string): Promise<string> => (await resolve(cwd)).dir;
+
+	const rootFor = async (cwd: string): Promise<string | undefined> => (await resolve(cwd)).root;
+
 	const write = async (cwd: string, input: WritePlanInput): Promise<WrittenPlan> => {
 		const base = baseOf(cwd);
 		const title = input.title.trim();
@@ -257,11 +343,10 @@ export function createPlanStore(pi: ExtensionAPI, options: { now?: () => Date }
 
 		const dir = await dirFor(base);
 		mkdirSync(dir, { recursive: true });
-		ensureIgnored(dir);
 
 		let path: string;
 		if (input.planPath) {
-			const resolved = resolve(base, input.planPath);
+			const resolved = resolvePlanArg(dir, input.planPath);
 			if (!isContainedPlan(dir, resolved)) {
 				throw new Error("plan_path must be a markdown plan file inside the plans directory.");
 			}
@@ -275,20 +360,30 @@ export function createPlanStore(pi: ExtensionAPI, options: { now?: () => Date }
 			throw new Error("The plan path is not writable inside the plans directory.");
 		}
 
-		writeAtomic(path, input.content);
-		return { path, relativePath: relativeTo(base, path), title, content: input.content, bytes };
+		// A refinement rewrites the body but not the review: every stored comment is
+		// carried onto the block whose text survived, so revising a plan under review
+		// does not silently discard what a teammate wrote.
+		const previous = existsSync(path) ? readFileSync(path, "utf-8") : undefined;
+		const content = previous === undefined ? carryFeedback("", input.content) : carryFeedback(previous, input.content);
+		const nextBytes = Buffer.byteLength(content, "utf-8");
+		if (nextBytes > MAX_PLAN_BYTES) {
+			throw new Error(`The plan is too large with its review comments (${nextBytes} bytes).`);
+		}
+
+		writeAtomic(path, content);
+		return { path, relativePath: shortenPath(path), title, content, bytes: nextBytes };
 	};
 
 	const read = async (cwd: string, planPath: string): Promise<StoredPlan | undefined> => {
 		const base = baseOf(cwd);
 		const dir = await dirFor(base);
-		const resolved = resolve(base, planPath);
+		const resolved = resolvePlanArg(dir, planPath);
 		if (!isContainedPlan(dir, resolved) || !existsSync(resolved)) return undefined;
 		try {
 			const content = readFileSync(resolved, "utf-8");
 			return {
 				path: resolved,
-				relativePath: relativeTo(base, resolved),
+				relativePath: shortenPath(resolved),
 				content,
 				bytes: Buffer.byteLength(content, "utf-8"),
 			};
@@ -333,14 +428,27 @@ export function createPlanStore(pi: ExtensionAPI, options: { now?: () => Date }
 	};
 
 	/**
-	 * Write the browser review comments into an existing plan, replacing any
-	 * feedback already stored there. The file must already be a contained plan,
-	 * so this is the same path-safe write as `setSteps`.
+	 * Write the browser review comments into an existing plan, replacing the
+	 * comments of `options.author` (the owner when absent) and leaving every other
+	 * writer's in place. The file must already be a contained plan, so this is the
+	 * same path-safe write as `setSteps`.
 	 */
-	const saveFeedback = async (cwd: string, planPath: string, annotations: PlanAnnotation[]): Promise<StoredPlan> => {
+	const saveFeedback = async (
+		cwd: string,
+		planPath: string,
+		annotations: PlanAnnotation[],
+		options: { author?: string } = {},
+	): Promise<StoredPlan> => {
 		const plan = await read(cwd, planPath);
 		if (!plan) throw new Error("No plan file there; pass a plan_path written by write_plan.");
-		const content = formatFeedback(plan.content, annotations);
+		const author = normalizeAuthor(options.author);
+		// An untagged entry is the writer's own; one tagged with a different name is
+		// another writer's comment, so it is dropped rather than re-signed.
+		const own = annotations.filter((annotation) => {
+			const who = normalizeAuthor(annotation.author);
+			return who === "" || who === author;
+		});
+		const content = formatFeedback(plan.content, own, { author });
 		writeAtomic(plan.path, content);
 		return {
 			path: plan.path,
@@ -417,7 +525,7 @@ export function createPlanStore(pi: ExtensionAPI, options: { now?: () => Date }
 
 			const summary: PlanSummary = {
 				path,
-				relativePath: relativeTo(base, path),
+				relativePath: shortenPath(path),
 				title: planTitle(name),
 				modified: info.mtimeMs,
 				bytes: info.size,
@@ -448,5 +556,5 @@ export function createPlanStore(pi: ExtensionAPI, options: { now?: () => Date }
 		return summaries;
 	};
 
-	return { dirFor, write, read, latest, index, setSteps, saveFeedback };
+	return { dirFor, rootFor, write, read, latest, index, setSteps, saveFeedback, takeNotice };
 }

package/extensions/plan/review-prompt.ts

@@ -0,0 +1,93 @@
+/**
+ * Pure rendering and parsing for the compact remote plan review.
+ *
+ * The prompt and its reply share one action table, so changing a number or a
+ * localized label cannot leave the parser behind. File delivery and the review
+ * lifecycle stay in `review.ts`.
+ */
+
+import type { InteractionLanguage } from "../../lib/interaction.ts";
+import { extractPlanSteps } from "./steps.ts";
+
+/** The actions the compact prompt can resolve without a refinement. */
+export type PlanReviewAction = "approve" | "keep" | "cancel";
+
+/** One editor reply: an action, or free text the model should apply. */
+export type PlanReviewReply =
+	| { action: "approve" }
+	| { action: "keep" }
+	| { action: "cancel" }
+	| { action: "refine"; refinement: string };
+
+interface ReviewAction {
+	key: string;
+	action: PlanReviewAction;
+	zh: string;
+	en: string;
+	words: readonly string[];
+}
+
+/** The action line and the parser read this one table, in display order. */
+const REVIEW_ACTIONS: readonly ReviewAction[] = [
+	{ key: "1", action: "approve", zh: "批准", en: "approve", words: ["approve", "批准", "同意"] },
+	{
+		key: "2",
+		action: "keep",
+		zh: "继续规划",
+		en: "keep planning",
+		words: ["keep", "keep planning", "继续", "继续规划"],
+	},
+	{ key: "3", action: "cancel", zh: "退出", en: "exit", words: ["exit", "cancel", "quit", "退出", "取消"] },
+];
+
+/** How much of one step the remote digest shows. */
+const DIGEST_STEP_CHARS = 90;
+
+/**
+ * One compact remote prompt: title, first steps, mode status, and the action
+ * line. The plan file is sent before it; a non-action reply refines the plan.
+ */
+export function planReviewPrompt(content: string, language: InteractionLanguage, attached: boolean): string {
+	const title = /^#\s+(.+)$/m.exec(content)?.[1]?.trim();
+	const steps = extractPlanSteps(content);
+	const count = steps.length;
+	const head =
+		language === "zh"
+			? `计划${title ? `：${title}` : ""}${count > 0 ? `（${count} 步）` : ""}`
+			: `Plan${title ? `: ${title}` : ""}${count > 0 ? ` (${count} step${count === 1 ? "" : "s"})` : ""}`;
+	const preview = steps.slice(0, 3).map((step, index) => {
+		const text = step.content.replace(/\s+/g, " ").trim();
+		const shown = text.length > DIGEST_STEP_CHARS ? `${text.slice(0, DIGEST_STEP_CHARS - 1)}…` : text;
+		return `${index + 1}. ${shown}`;
+	});
+	const more =
+		count > preview.length
+			? language === "zh"
+				? `… 还有 ${count - preview.length} 步`
+				: `… (${count - preview.length} more)`
+			: "";
+	const status = language === "zh" ? "Plan 模式开启，写入已关闭。" : "Plan mode is on — write access is off.";
+	const attachment = attached ? (language === "zh" ? "计划已在上方。" : "The plan is above.") : "";
+	const choices = REVIEW_ACTIONS.map((action) => `${action.key} ${action[language]}`).join(
+		language === "zh" ? "，" : ", ",
+	);
+	const actions =
+		language === "zh"
+			? `回复 ${choices}；或直接输入修改意见（想做别的先退出或批准）。`
+			: `Reply ${choices} — or type feedback to revise. To ask something else, exit or approve first.`;
+	return [head, ...preview, more, status, attachment, actions].filter((line) => line !== "").join("\n");
+}
+
+/**
+ * Parse the one editor reply. Only an exact number or action word is an action;
+ * any other non-empty text is a refinement request.
+ */
+export function parsePlanReviewReply(raw: string): PlanReviewReply {
+	const text = raw.trim();
+	if (text === "") return { action: "cancel" };
+	const key = text.toLowerCase();
+	for (const action of REVIEW_ACTIONS) {
+		if (key === action.key || action.words.includes(key)) return { action: action.action };
+	}
+	return { action: "refine", refinement: text };
+}