@ilya-lesikov/pi-pi 0.1.0

package/3p/pi-plannotator/apps/pi-extension/plannotator-events.ts

@@ -0,0 +1,342 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { DiffType, VcsSelection } from "./server.js";
+import { getRecentAssistantMessages } from "./assistant-message.js";
+import {
+	getLastAssistantMessageText,
+	getStartupErrorMessage,
+	openArchiveBrowserAction,
+	openCodeReview,
+	openLastMessageAnnotation,
+	openMarkdownAnnotation,
+	startCodeReviewBrowserSession,
+	startLastMessageAnnotationSession,
+	startMarkdownAnnotationSession,
+	startPlanReviewBrowserSession,
+} from "./plannotator-browser.js";
+
+export const PLANNOTATOR_REQUEST_CHANNEL = "plannotator:request" as const;
+export const PLANNOTATOR_REVIEW_RESULT_CHANNEL = "plannotator:review-result" as const;
+export const PLANNOTATOR_TIMEOUT_MS = 5_000;
+
+export type PlannotatorAction =
+	| "plan-review"
+	| "review-status"
+	| "code-review"
+	| "annotate"
+	| "annotate-last"
+	| "archive";
+
+export interface PlannotatorHandledResponse<T> {
+	status: "handled";
+	result: T;
+}
+
+export interface PlannotatorUnavailableResponse {
+	status: "unavailable";
+	error?: string;
+}
+
+export interface PlannotatorErrorResponse {
+	status: "error";
+	error: string;
+}
+
+export type PlannotatorResponse<T> =
+	| PlannotatorHandledResponse<T>
+	| PlannotatorUnavailableResponse
+	| PlannotatorErrorResponse;
+
+export interface PlannotatorRequestBase<A extends PlannotatorAction, P, R> {
+	requestId: string;
+	action: A;
+	payload: P;
+	respond: (response: PlannotatorResponse<R>) => void;
+}
+
+export interface PlannotatorPlanReviewPayload {
+	planFilePath?: string;
+	planContent: string;
+	origin?: string;
+}
+
+export interface PlannotatorPlanReviewStartResult {
+	status: "pending";
+	reviewId: string;
+}
+
+export interface PlannotatorReviewResultEvent {
+	reviewId: string;
+	approved: boolean;
+	feedback?: string;
+	savedPath?: string;
+	agentSwitch?: string;
+	permissionMode?: string;
+}
+
+export interface PlannotatorReviewStatusPayload {
+	reviewId: string;
+}
+
+export type PlannotatorReviewStatusResult =
+	| { status: "pending" }
+	| ({ status: "completed" } & PlannotatorReviewResultEvent)
+	| { status: "missing" };
+
+export interface PlannotatorCodeReviewPayload {
+	diffType?: DiffType;
+	defaultBranch?: string;
+	vcsType?: VcsSelection;
+	useLocal?: boolean;
+	cwd?: string;
+	prUrl?: string;
+}
+
+export interface PlannotatorCodeReviewResult {
+	approved: boolean;
+	feedback?: string;
+	annotations?: unknown[];
+	agentSwitch?: string;
+}
+
+export interface PlannotatorAnnotatePayload {
+	filePath: string;
+	markdown?: string;
+	mode?: "annotate" | "annotate-folder" | "annotate-last";
+	folderPath?: string;
+	/** Enable review-gate UX (Approve / Annotate / Close). */
+	gate?: boolean;
+}
+
+export interface PlannotatorAnnotationResult {
+	feedback: string;
+	/** True when the reviewer closed the session without providing feedback. */
+	exit?: boolean;
+	/** True when the reviewer clicked Approve in review-gate mode. */
+	approved?: boolean;
+}
+
+export interface PlannotatorArchivePayload {
+	customPlanPath?: string;
+}
+
+export interface PlannotatorArchiveResult {
+	opened: boolean;
+}
+
+export type PlannotatorRequestMap = {
+	"plan-review": PlannotatorRequestBase<"plan-review", PlannotatorPlanReviewPayload, PlannotatorPlanReviewStartResult>;
+	"review-status": PlannotatorRequestBase<"review-status", PlannotatorReviewStatusPayload, PlannotatorReviewStatusResult>;
+	"code-review": PlannotatorRequestBase<"code-review", PlannotatorCodeReviewPayload, PlannotatorCodeReviewResult>;
+	annotate: PlannotatorRequestBase<"annotate", PlannotatorAnnotatePayload, PlannotatorAnnotationResult>;
+	"annotate-last": PlannotatorRequestBase<"annotate-last", PlannotatorAnnotatePayload, PlannotatorAnnotationResult>;
+	archive: PlannotatorRequestBase<"archive", PlannotatorArchivePayload, PlannotatorArchiveResult>;
+};
+export type PlannotatorRequest = PlannotatorRequestMap[PlannotatorAction];
+export type PlannotatorResponseMap = {
+	"plan-review": PlannotatorResponse<PlannotatorPlanReviewStartResult>;
+	"review-status": PlannotatorResponse<PlannotatorReviewStatusResult>;
+	"code-review": PlannotatorResponse<PlannotatorCodeReviewResult>;
+	annotate: PlannotatorResponse<PlannotatorAnnotationResult>;
+	"annotate-last": PlannotatorResponse<PlannotatorAnnotationResult>;
+	archive: PlannotatorResponse<PlannotatorArchiveResult>;
+};
+function isPlannotatorAction(value: unknown): value is PlannotatorAction {
+	return (
+		value === "plan-review" ||
+		value === "review-status" ||
+		value === "code-review" ||
+		value === "annotate" ||
+		value === "annotate-last" ||
+		value === "archive"
+	);
+}
+
+const REVIEW_STATUS_PATH = join(homedir(), ".pi", "plannotator-review-status.json");
+
+type StoredReviewStatus = Record<string, PlannotatorReviewStatusResult>;
+
+function readStoredReviewStatuses(): StoredReviewStatus {
+	try {
+		if (!existsSync(REVIEW_STATUS_PATH)) return {};
+		const raw = readFileSync(REVIEW_STATUS_PATH, "utf-8");
+		const parsed = JSON.parse(raw) as StoredReviewStatus;
+		return parsed && typeof parsed === "object" ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+
+function writeStoredReviewStatuses(statuses: StoredReviewStatus): void {
+	mkdirSync(dirname(REVIEW_STATUS_PATH), { recursive: true });
+	writeFileSync(REVIEW_STATUS_PATH, JSON.stringify(statuses, null, 2));
+}
+
+function setStoredReviewStatus(reviewId: string, status: PlannotatorReviewStatusResult): void {
+	const statuses = readStoredReviewStatuses();
+	statuses[reviewId] = status;
+	writeStoredReviewStatuses(statuses);
+}
+
+function getStoredReviewStatus(reviewId: string): PlannotatorReviewStatusResult {
+	return readStoredReviewStatuses()[reviewId] ?? { status: "missing" };
+}
+
+function createActiveSessionContext() {
+	let currentCtx: ExtensionContext | undefined;
+
+	return {
+		set(ctx: ExtensionContext): void {
+			currentCtx = ctx;
+		},
+		clear(): void {
+			currentCtx = undefined;
+		},
+		get(): ExtensionContext | undefined {
+			return currentCtx;
+		},
+	};
+}
+
+export function registerPlannotatorEventListeners(pi: ExtensionAPI): void {
+	const activeSessionContext = createActiveSessionContext();
+
+	// Plannotator event requests are handled against the latest active session.
+	// The active context is intentionally session-scoped and replaced on each session_start.
+	pi.on("session_start", async (_event, ctx) => {
+		activeSessionContext.set(ctx);
+	});
+	pi.events.on(PLANNOTATOR_REQUEST_CHANNEL, async (data) => {
+		const request = data as Partial<PlannotatorRequest> | null;
+		const ctx = activeSessionContext.get();
+
+		if (!request || typeof request.respond !== "function" || !isPlannotatorAction(request.action)) {
+			return;
+		}
+
+		try {
+			if (request.action === "review-status") {
+				const reviewId = request.payload?.reviewId;
+				if (typeof reviewId !== "string" || !reviewId.trim()) {
+					request.respond({ status: "error", error: "Missing reviewId for review-status request." });
+					return;
+				}
+				request.respond({ status: "handled", result: getStoredReviewStatus(reviewId) });
+				return;
+			}
+
+			if (!ctx) {
+				request.respond({ status: "unavailable", error: "Plannotator context is not ready yet." });
+				return;
+			}
+
+			switch (request.action) {
+				case "plan-review": {
+					const planContent = request.payload?.planContent;
+					if (typeof planContent !== "string" || !planContent.trim()) {
+						request.respond({ status: "error", error: "Missing planContent for plan-review request." });
+						return;
+					}
+					const session = await startPlanReviewBrowserSession(ctx, planContent);
+					setStoredReviewStatus(session.reviewId, { status: "pending" });
+					session.onDecision((result) => {
+						const reviewResult = {
+							reviewId: session.reviewId,
+							approved: result.approved,
+							feedback: result.feedback,
+							savedPath: result.savedPath,
+							agentSwitch: result.agentSwitch,
+							permissionMode: result.permissionMode,
+						} satisfies PlannotatorReviewResultEvent;
+						setStoredReviewStatus(session.reviewId, { status: "completed", ...reviewResult });
+						pi.events.emit(PLANNOTATOR_REVIEW_RESULT_CHANNEL, reviewResult);
+					});
+					request.respond({
+						status: "handled",
+						result: {
+							status: "pending",
+							reviewId: session.reviewId,
+						},
+					});
+					return;
+				}
+				case "code-review": {
+					const result = await openCodeReview(ctx, {
+						cwd: request.payload?.cwd,
+						defaultBranch: request.payload?.defaultBranch,
+						diffType: request.payload?.diffType,
+						vcsType: request.payload?.vcsType,
+						useLocal: request.payload?.useLocal,
+						prUrl: request.payload?.prUrl,
+					});
+					request.respond({ status: "handled", result });
+					return;
+				}
+				case "annotate": {
+					const payload = request.payload;
+					if (!payload?.filePath) {
+						request.respond({ status: "error", error: "Missing filePath for annotate request." });
+						return;
+					}
+					const sourceConverted = /\.html?$/i.test(payload.filePath) || /^https?:\/\//i.test(payload.filePath);
+					const result = await openMarkdownAnnotation(
+						ctx,
+						payload.filePath,
+						payload.markdown ?? "",
+						payload.mode ?? "annotate",
+						payload.folderPath,
+						undefined,
+						sourceConverted,
+						payload.gate,
+					);
+					request.respond({ status: "handled", result });
+					return;
+				}
+				case "annotate-last": {
+					const payload = request.payload;
+					const usePayloadText = !!payload?.markdown?.trim();
+					const lastText = usePayloadText ? payload!.markdown! : getLastAssistantMessageText(ctx);
+					if (!lastText) {
+						request.respond({ status: "unavailable", error: "No assistant message found in session." });
+						return;
+					}
+					const recent = usePayloadText ? [] : getRecentAssistantMessages(ctx, 25);
+					const pickerMessages = recent.length > 1 ? recent : undefined;
+					const result = await openLastMessageAnnotation(ctx, lastText, payload?.gate, pickerMessages);
+					request.respond({ status: "handled", result });
+					return;
+				}
+				case "archive": {
+					const result = await openArchiveBrowserAction(ctx, request.payload?.customPlanPath);
+					request.respond({ status: "handled", result });
+					return;
+				}
+			}
+		} catch (err) {
+			const message = getStartupErrorMessage(err);
+			if (/unavailable|not available/i.test(message)) {
+				request.respond({ status: "unavailable", error: message });
+				return;
+			}
+			request.respond({ status: "error", error: message });
+		}
+	});
+}
+
+export {
+	getLastAssistantMessageText,
+	hasPlanBrowserHtml,
+	hasReviewBrowserHtml,
+	startCodeReviewBrowserSession,
+	startLastMessageAnnotationSession,
+	startMarkdownAnnotationSession,
+	getStartupErrorMessage,
+	openArchiveBrowserAction,
+	openCodeReview,
+	openLastMessageAnnotation,
+	openMarkdownAnnotation,
+	openPlanReviewBrowser,
+	startPlanReviewBrowserSession,
+} from "./plannotator-browser.js";

package/3p/pi-plannotator/apps/pi-extension/plannotator.json

@@ -0,0 +1,12 @@
+{
+  "phases": {
+    "planning": {
+      "activeTools": ["grep", "find", "ls", "plannotator_submit_plan"],
+      "statusLabel": "⏸ plan",
+      "systemPrompt": "[PLANNOTATOR - PLANNING PHASE]\nYou are in plan mode. You MUST NOT make any changes to the codebase — no edits, no commits, no installs, no destructive commands. During planning you may only write or edit markdown files (.md, .mdx) inside the working directory.\n\nAvailable tools: read, bash, grep, find, ls, write (markdown only), edit (markdown only), plannotator_submit_plan\n\nDo not run destructive bash commands (rm, git push, npm install, etc.) — focus on reading and exploring the codebase. Web fetching (curl, wget) is fine.\n\n## Iterative Planning Workflow\n\nYou are pair-planning with the user. Explore the code to build context, then write your findings into a markdown plan file as you go. The plan starts as a rough skeleton and gradually becomes the final plan.\n\n### Picking a plan file\n\nChoose a descriptive filename for your plan. Convention: `PLAN.md` at the repo root for a single focused plan, or `plans/<short-name>.md` for projects that keep multiple plans. Reuse the same filename across revisions of the same plan so version history links up.\n\n### The Loop\n\nRepeat this cycle until the plan is complete:\n\n1. **Explore** — Use read, grep, find, ls, and bash to understand the codebase. Actively search for existing functions, utilities, and patterns that can be reused — avoid proposing new code when suitable implementations already exist.\n2. **Update the plan file** — After each discovery, immediately capture what you learned in the plan. Don't wait until the end. Use write for the initial draft, then edit for all subsequent updates.\n3. **Ask the user** — When you hit an ambiguity or decision you can't resolve from code alone, ask. Then go back to step 1.\n\n### First Turn\n\nStart by quickly scanning key files to form an initial understanding of the task scope. Then write a skeleton plan (headers and rough notes) and ask the user your first round of questions. Don't explore exhaustively before engaging the user.\n\n### Asking Good Questions\n\n- Never ask what you could find out by reading the code.\n- Batch related questions together.\n- Focus on things only the user can answer: requirements, preferences, tradeoffs, edge-case priorities.\n- Scale depth to the task — a vague feature request needs many rounds; a focused bug fix may need one or none.\n\n### Plan File Structure\n\nYour plan file should use markdown with clear sections:\n- **Context** — Why this change is being made: the problem, what prompted it, the intended outcome.\n- **Approach** — Your recommended approach only, not all alternatives considered.\n- **Files to modify** — List the critical file paths that will be changed.\n- **Reuse** — Reference existing functions and utilities you found, with their file paths.\n- **Steps** — Implementation checklist:\n  - [ ] Step 1 description\n  - [ ] Step 2 description\n- **Verification** — How to test the changes end-to-end (run the code, run tests, manual checks).\n\nKeep the plan concise enough to scan quickly, but detailed enough to execute effectively.\n\n### When to Submit\n\nYour 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 plannotator_submit_plan with the path to your plan file to submit for review.\n\n### Revising After Feedback\n\nWhen the user denies a plan with feedback:\n1. Read the plan file to see the current plan.\n2. Use the edit tool to make targeted changes addressing the feedback — do NOT rewrite the entire file.\n3. Call plannotator_submit_plan again with the same filePath to resubmit.\n\n### Ending Your Turn\n\nYour turn should only end by either:\n- Asking the user a question to gather more information.\n- Calling plannotator_submit_plan when the plan is ready for review.\n\nDo not end your turn without doing one of these two things."
+    },
+    "executing": {
+      "systemPrompt": "[PLANNOTATOR - EXECUTING PLAN]\nFull tool access is enabled. Execute the plan from ${planFilePath}.\n\nRemaining steps:\n${todoList}\n\nExecute each step in order. After completing a step, include [DONE:n] in your response where n is the step number."
+    }
+  }
+}