pi-plan-task 1.0.0

package/extensions/framing.ts

@@ -0,0 +1,79 @@
+export const PLAN_FRAMING_TYPE = "pi-plan-task-plan";
+export const BUILD_FRAMING_TYPE = "pi-plan-task-build";
+export const BUILD_STATUS_TYPE = "pi-plan-task-status";
+
+const PLAN_TASK_CUSTOM_TYPES = new Set<string>([
+	PLAN_FRAMING_TYPE,
+	BUILD_FRAMING_TYPE,
+	BUILD_STATUS_TYPE,
+]);
+
+export type FramingMode = "idle" | "plan" | "build";
+export type InjectionKind = "plan-framing" | "build-framing" | "build-status";
+
+export interface FramingState {
+	planFramingDelivered: boolean;
+	framedTaskId?: number;
+	lastStatusKey?: string;
+}
+
+export const INITIAL_FRAMING_STATE: FramingState = {
+	planFramingDelivered: false,
+};
+
+export function isPlanTaskCustomMessage(
+	message: unknown,
+): message is { role: "custom"; customType: string } {
+	if (!message || typeof message !== "object") return false;
+	const rec = message as { role?: unknown; customType?: unknown };
+	return rec.role === "custom" && typeof rec.customType === "string" && PLAN_TASK_CUSTOM_TYPES.has(rec.customType);
+}
+
+function keepTypes(mode: FramingMode): Set<string> {
+	if (mode === "plan") return new Set([PLAN_FRAMING_TYPE]);
+	if (mode === "build") return new Set([BUILD_FRAMING_TYPE, BUILD_STATUS_TYPE]);
+	return new Set();
+}
+
+/** Keep only the newest framing for the current phase. Drop all injected messages while idle. */
+export function filterFramingMessages<T>(messages: readonly T[], mode: FramingMode): T[] {
+	const keep = keepTypes(mode);
+	const lastIndex = new Map<string, number>();
+	messages.forEach((message, index) => {
+		if (!isPlanTaskCustomMessage(message) || !keep.has(message.customType)) return;
+		lastIndex.set(message.customType, index);
+	});
+	return messages.filter((message, index) => {
+		if (!isPlanTaskCustomMessage(message)) return true;
+		if (!keep.has(message.customType)) return false;
+		return lastIndex.get(message.customType) === index;
+	});
+}
+
+export function nextInjection(
+	mode: FramingMode,
+	state: FramingState,
+	currentTaskId?: number,
+	statusKey?: string,
+): InjectionKind | undefined {
+	if (mode === "plan") return state.planFramingDelivered ? undefined : "plan-framing";
+	if (mode !== "build" || currentTaskId === undefined) return undefined;
+	if (state.framedTaskId !== currentTaskId) return "build-framing";
+	if (statusKey !== undefined && statusKey !== state.lastStatusKey) return "build-status";
+	return undefined;
+}
+
+export function rememberInjection(
+	state: FramingState,
+	kind: InjectionKind,
+	taskId?: number,
+	statusKey?: string,
+): FramingState {
+	if (kind === "plan-framing") {
+		return { ...state, planFramingDelivered: true };
+	}
+	if (kind === "build-framing") {
+		return { ...state, framedTaskId: taskId, lastStatusKey: statusKey };
+	}
+	return { ...state, lastStatusKey: statusKey };
+}

package/extensions/index.ts

@@ -0,0 +1,549 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import {
+	type ExtensionAPI,
+	type ExtensionContext,
+	isToolCallEventType,
+} from "@earendil-works/pi-coding-agent";
+import { matchesKey, Text, truncateToWidth } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { isSafePlanCommand } from "./bash-guard.ts";
+import {
+	ASK_QUESTION_GUIDELINES,
+	ASK_USER_QUESTION_TOOL,
+	executeAskQuestion,
+} from "./ask-question.ts";
+import { ensureDefaultGlobalConfig, loadConfig } from "./config.ts";
+import {
+	ensurePlanDir,
+	formatProgress,
+	loadTaskFile,
+	markTaskComplete,
+	nextPendingTask,
+	readOptionalFile,
+} from "./files.ts";
+import {
+	BUILD_FRAMING_TYPE,
+	BUILD_STATUS_TYPE,
+	filterFramingMessages,
+	INITIAL_FRAMING_STATE,
+	nextInjection,
+	PLAN_FRAMING_TYPE,
+	rememberInjection,
+	type FramingState,
+} from "./framing.ts";
+import { EMPTY_PLAN_SOURCE, loadPlanSource, type PlanSource } from "./plan-input.ts";
+import { isPlanArtifactPath, planFilePath, taskFilePath } from "./paths.ts";
+import { buildPrompt, buildRequest, buildStatus, buildStatusKey, planPrompt, planRequest } from "./prompts.ts";
+import type { TaskItem } from "./types.ts";
+
+type Mode = "idle" | "plan" | "build";
+
+const CONTINUE_THIS = "Continue in this session";
+const CONTINUE_NEW = "Continue in a new session";
+
+const ALWAYS_ON_TOOLS = ["plan_task", ASK_USER_QUESTION_TOOL] as const;
+
+function unique(names: string[]): string[] {
+	return [...new Set(names)];
+}
+
+function withAlwaysOnTools(names: string[]): string[] {
+	return unique([...names, ...ALWAYS_ON_TOOLS]);
+}
+
+function pathFromInput(input: unknown): string | undefined {
+	if (!input || typeof input !== "object") return undefined;
+	const path = (input as { path?: unknown }).path;
+	return typeof path === "string" ? path : undefined;
+}
+
+function formatTaskList(tasks: TaskItem[]): string {
+	if (tasks.length === 0) return "No tasks found in .plan_task/task.md.";
+	const lines = tasks.map((task) => {
+		const mark = task.done ? "[x]" : "[ ]";
+		return `${mark} ${task.id}. ${task.title}`;
+	});
+	return `Progress ${formatProgress(tasks)}\n${lines.join("\n")}`;
+}
+
+class TaskListComponent {
+	private readonly tasks: TaskItem[];
+	private readonly theme: { fg: (name: string, text: string) => string };
+	private readonly onClose: () => void;
+	private cachedWidth?: number;
+	private cachedLines?: string[];
+
+	constructor(
+		tasks: TaskItem[],
+		theme: { fg: (name: string, text: string) => string },
+		onClose: () => void,
+	) {
+		this.tasks = tasks;
+		this.theme = theme;
+		this.onClose = onClose;
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) {
+			this.onClose();
+		}
+	}
+
+	render(width: number): string[] {
+		if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
+		const th = this.theme;
+		const lines = ["", truncateToWidth(`  ${th.fg("accent", "Plan tasks")}  ${th.fg("muted", formatProgress(this.tasks))}`, width), ""];
+		if (this.tasks.length === 0) {
+			lines.push(truncateToWidth(`  ${th.fg("dim", "No tasks found. Run /plan first.")}`, width));
+		} else {
+			for (const task of this.tasks) {
+				const check = task.done ? th.fg("success", "x") : th.fg("dim", " ");
+				const title = task.done ? th.fg("dim", task.title) : th.fg("text", task.title);
+				lines.push(truncateToWidth(`  [${check}] ${th.fg("accent", String(task.id))}. ${title}`, width));
+			}
+		}
+		lines.push("", truncateToWidth(`  ${th.fg("dim", "Press Escape to close")}`, width), "");
+		this.cachedWidth = width;
+		this.cachedLines = lines;
+		return lines;
+	}
+
+	invalidate(): void {
+		this.cachedWidth = undefined;
+		this.cachedLines = undefined;
+	}
+}
+
+export default async function planTaskExtension(pi: ExtensionAPI): Promise<void> {
+	await ensureDefaultGlobalConfig();
+
+	let mode: Mode = "idle";
+	let continueAll = false;
+	let currentTaskId: number | undefined;
+	let toolsBeforePlan: string[] | undefined;
+	let awaitingChoice = false;
+	let planReadyNotified = false;
+	let planSource: PlanSource = EMPTY_PLAN_SOURCE;
+	let framing: FramingState = { ...INITIAL_FRAMING_STATE };
+
+	function resetFraming(): void {
+		framing = { ...INITIAL_FRAMING_STATE };
+	}
+
+	function updateStatus(ctx: ExtensionContext, tasks?: TaskItem[]): void {
+		if (mode === "plan") {
+			ctx.ui.setStatus("pi-plan-task", ctx.ui.theme.fg("warning", "plan"));
+			ctx.ui.setWidget("pi-plan-task", undefined);
+			return;
+		}
+		if (mode === "build" && tasks && tasks.length > 0) {
+			ctx.ui.setStatus("pi-plan-task", ctx.ui.theme.fg("accent", `build ${formatProgress(tasks)}`));
+			ctx.ui.setWidget(
+				"pi-plan-task",
+				tasks.map((task) => {
+					if (task.done) {
+						return ctx.ui.theme.fg("success", "x ") + ctx.ui.theme.fg("muted", `${task.id}. ${task.title}`);
+					}
+					const prefix = task.id === currentTaskId ? ctx.ui.theme.fg("accent", "> ") : "  ";
+					return `${prefix}${task.id}. ${task.title}`;
+				}),
+			);
+			return;
+		}
+		ctx.ui.setStatus("pi-plan-task", undefined);
+		ctx.ui.setWidget("pi-plan-task", undefined);
+	}
+
+	async function applyPlanTools(ctx: ExtensionContext): Promise<void> {
+		if (toolsBeforePlan === undefined) {
+			toolsBeforePlan = pi.getActiveTools();
+		}
+		const config = await loadConfig(ctx.cwd);
+		pi.setActiveTools(withAlwaysOnTools([...config.planTools, "write", "edit"]));
+	}
+
+	function restoreTools(): void {
+		if (toolsBeforePlan) {
+			pi.setActiveTools(withAlwaysOnTools(toolsBeforePlan));
+			toolsBeforePlan = undefined;
+			return;
+		}
+		pi.setActiveTools(withAlwaysOnTools(pi.getActiveTools()));
+	}
+
+	async function enterPlanMode(ctx: ExtensionContext): Promise<void> {
+		mode = "plan";
+		continueAll = false;
+		currentTaskId = undefined;
+		planReadyNotified = false;
+		resetFraming();
+		await ensurePlanDir(ctx.cwd);
+		await applyPlanTools(ctx);
+		updateStatus(ctx);
+	}
+
+	async function enterBuildMode(ctx: ExtensionContext): Promise<void> {
+		mode = "build";
+		resetFraming();
+		restoreTools();
+		const file = await loadTaskFile(ctx.cwd);
+		updateStatus(ctx, file?.tasks);
+	}
+
+	function leaveModes(ctx: ExtensionContext): void {
+		mode = "idle";
+		continueAll = false;
+		currentTaskId = undefined;
+		resetFraming();
+		restoreTools();
+		updateStatus(ctx);
+	}
+
+	async function startNextTask(ctx: ExtensionContext): Promise<boolean> {
+		const file = await loadTaskFile(ctx.cwd);
+		if (!file) {
+			ctx.ui.notify("No plan found. Run /plan first.", "error");
+			leaveModes(ctx);
+			return false;
+		}
+		const next = nextPendingTask(file.tasks);
+		if (!next) {
+			ctx.ui.notify("All tasks are complete.", "info");
+			leaveModes(ctx);
+			return false;
+		}
+		currentTaskId = next.id;
+		updateStatus(ctx, file.tasks);
+		pi.sendUserMessage(buildRequest(next));
+		return true;
+	}
+
+	async function afterBuildSettled(ctx: ExtensionContext): Promise<void> {
+		if (mode !== "build" || awaitingChoice || currentTaskId === undefined) return;
+		const file = await loadTaskFile(ctx.cwd);
+		if (!file) {
+			ctx.ui.notify("task.md is missing. Stopped.", "error");
+			leaveModes(ctx);
+			return;
+		}
+		const current = file.tasks.find((task) => task.id === currentTaskId);
+		updateStatus(ctx, file.tasks);
+		if (!current?.done) {
+			ctx.ui.notify(
+				`Task ${currentTaskId} is not marked complete. Update .plan_task/task.md or call plan_task, then run /build again.`,
+				"warning",
+			);
+			return;
+		}
+		if (file.tasks.every((task) => task.done)) {
+			ctx.ui.notify("All tasks are complete.", "info");
+			leaveModes(ctx);
+			return;
+		}
+		if (continueAll) {
+			await startNextTask(ctx);
+			return;
+		}
+		if (!ctx.hasUI) {
+			ctx.ui.notify("Task complete. Run /build for the next task.", "info");
+			mode = "idle";
+			currentTaskId = undefined;
+			resetFraming();
+			updateStatus(ctx);
+			return;
+		}
+		awaitingChoice = true;
+		const choice = await ctx.ui.select("Task complete. What next?", [CONTINUE_THIS, CONTINUE_NEW]);
+		awaitingChoice = false;
+		if (choice === CONTINUE_THIS) {
+			await startNextTask(ctx);
+			return;
+		}
+		if (choice === CONTINUE_NEW) {
+			mode = "idle";
+			currentTaskId = undefined;
+			resetFraming();
+			updateStatus(ctx);
+			pi.sendUserMessage("/build-next-session", { expandPromptTemplates: true });
+			return;
+		}
+		mode = "idle";
+		currentTaskId = undefined;
+		resetFraming();
+		updateStatus(ctx);
+	}
+
+	pi.registerTool({
+		name: "plan_task",
+		label: "Plan Task",
+		description: "Read plan progress or mark a planned task complete in .plan_task/task.md",
+		promptSnippet: "Mark planned tasks complete and read .plan_task progress",
+		parameters: Type.Object({
+			action: StringEnum(["status", "complete"] as const),
+			id: Type.Optional(Type.Number({ description: "Task id to mark complete" })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const file = await loadTaskFile(ctx.cwd);
+			if (!file) {
+				return { content: [{ type: "text", text: "No .plan_task/task.md found. Run /plan first." }] };
+			}
+			if (params.action === "status") {
+				return { content: [{ type: "text", text: formatTaskList(file.tasks) }], details: { tasks: file.tasks } };
+			}
+			if (params.id === undefined) {
+				return { content: [{ type: "text", text: "id is required for complete" }] };
+			}
+			const next = await markTaskComplete(ctx.cwd, params.id);
+			if (!next) {
+				return { content: [{ type: "text", text: "Could not update .plan_task/task.md" }] };
+			}
+			const task = next.tasks.find((item) => item.id === params.id);
+			updateStatus(ctx, next.tasks);
+			return {
+				content: [
+					{
+						type: "text",
+						text: task?.done
+							? `Marked task ${params.id} complete. Progress ${formatProgress(next.tasks)}.`
+							: `Task ${params.id} was not found.`,
+					},
+				],
+				details: { tasks: next.tasks, completedId: params.id },
+			};
+		},
+		renderCall(args, theme) {
+			const suffix = args.id === undefined ? "" : ` #${args.id}`;
+			return new Text(theme.fg("toolTitle", theme.bold("plan_task ")) + theme.fg("muted", `${args.action}${suffix}`), 0, 0);
+		},
+	});
+
+	pi.registerTool({
+		name: ASK_USER_QUESTION_TOOL,
+		label: "Ask User Question",
+		description:
+			"Ask user a clarifying question with selectable options, a recommended default, and optional free-form input. Works in any mode.",
+		promptSnippet:
+			"Ask user a clarifying question with 2-4 options and a recommended default; works in any mode",
+		promptGuidelines: ASK_QUESTION_GUIDELINES,
+		parameters: Type.Object({
+			question: Type.String({ description: "The clarifying question to ask" }),
+			options: Type.Array(
+				Type.Object({
+					label: Type.String({ description: "Option label" }),
+					description: Type.Optional(Type.String({ description: "Optional explanation" })),
+				}),
+				{ description: "Options to choose from (2-4 required)", minItems: 2, maxItems: 4 },
+			),
+			recommended: Type.Optional(
+				Type.String({
+					description:
+						"Label of the recommended option (must match one option label). It is shown with a ★ marker.",
+				}),
+			),
+			allowOther: Type.Optional(Type.Boolean({ description: "Allow free-form user answer; default true" })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			return executeAskQuestion(params, ctx);
+		},
+		renderCall(args, theme) {
+			const question = typeof args.question === "string" ? args.question : "";
+			return new Text(
+				theme.fg("toolTitle", theme.bold("ask_user_question ")) + theme.fg("muted", question),
+				0,
+				0,
+			);
+		},
+	});
+	pi.registerCommand("plan", {
+		description: "Write .plan_task/plan.md and .plan_task/task.md from a file path or prompt",
+		handler: async (args, ctx) => {
+			if (mode === "build") {
+				const ok = ctx.hasUI
+					? await ctx.ui.confirm("Switch to plan mode?", "A build is in progress. Stop it and start planning?")
+					: true;
+				if (!ok) return;
+			}
+			const loaded = await loadPlanSource(args, ctx.cwd);
+			if (!loaded.ok) {
+				ctx.ui.notify(loaded.error, "error");
+				return;
+			}
+			const existing = await readOptionalFile(taskFilePath(ctx.cwd));
+			if (existing && ctx.hasUI) {
+				const ok = await ctx.ui.confirm("Overwrite existing plan?", ".plan_task already has a task list. Overwrite it?");
+				if (!ok) return;
+			}
+			planSource = loaded.source;
+			await enterPlanMode(ctx);
+			const message =
+				loaded.source.kind === "file"
+					? `Planning from ${loaded.source.displayPath}. Project writes are blocked.`
+					: "Plan mode enabled. Project writes are blocked.";
+			ctx.ui.notify(message, "info");
+			pi.sendUserMessage(planRequest(loaded.source));
+		},
+	});
+
+	async function beginBuild(ctx: ExtensionContext, runAll: boolean): Promise<void> {
+		const file = await loadTaskFile(ctx.cwd);
+		if (!file) {
+			ctx.ui.notify("No plan found. Run /plan first.", "error");
+			return;
+		}
+		if (file.tasks.length === 0) {
+			ctx.ui.notify("task.md has no checklist items.", "error");
+			return;
+		}
+		if (!nextPendingTask(file.tasks)) {
+			ctx.ui.notify("All tasks are complete.", "info");
+			return;
+		}
+		continueAll = runAll;
+		await enterBuildMode(ctx);
+		ctx.ui.notify(runAll ? "Building remaining tasks." : "Building the next task.", "info");
+		await startNextTask(ctx);
+	}
+
+	pi.registerCommand("build", {
+		description: "Execute the next planned task",
+		handler: async (_args, ctx) => {
+			await beginBuild(ctx, false);
+		},
+	});
+
+	pi.registerCommand("goal", {
+		description: "Execute remaining planned tasks until the list is complete",
+		handler: async (_args, ctx) => {
+			await beginBuild(ctx, true);
+		},
+	});
+
+	pi.registerCommand("tasks", {
+		description: "Show current plan tasks and progress",
+		handler: async (_args, ctx) => {
+			const file = await loadTaskFile(ctx.cwd);
+			const tasks = file?.tasks ?? [];
+			if (ctx.mode !== "tui") {
+				ctx.ui.notify(formatTaskList(tasks), "info");
+				return;
+			}
+			await ctx.ui.custom<void>((_tui, theme, _kb, done) => new TaskListComponent(tasks, theme, () => done()));
+		},
+	});
+
+	pi.registerCommand("build-next-session", {
+		description: "Continue the next planned task in a new session",
+		handler: async (_args, ctx) => {
+			const parentSession = ctx.sessionManager.getSessionFile();
+			const result = await ctx.newSession({
+				parentSession,
+				withSession: async (nextCtx) => {
+					await nextCtx.sendUserMessage("/build", { expandPromptTemplates: true });
+				},
+			});
+			if (result.cancelled) {
+				ctx.ui.notify("New session cancelled.", "info");
+			}
+		},
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		mode = "idle";
+		continueAll = false;
+		currentTaskId = undefined;
+		toolsBeforePlan = undefined;
+		awaitingChoice = false;
+		planReadyNotified = false;
+		planSource = EMPTY_PLAN_SOURCE;
+		resetFraming();
+		pi.setActiveTools(withAlwaysOnTools(pi.getActiveTools()));
+		updateStatus(ctx);
+	});
+
+	pi.on("before_agent_start", async (_event, ctx) => {
+		let statusKey: string | undefined;
+		let task: TaskItem | undefined;
+		let tasks: TaskItem[] | undefined;
+		let remaining = 0;
+		if (mode === "build" && currentTaskId !== undefined) {
+			const file = await loadTaskFile(ctx.cwd);
+			task = file?.tasks.find((item) => item.id === currentTaskId);
+			if (file && task) {
+				tasks = file.tasks;
+				statusKey = buildStatusKey(file.tasks, currentTaskId);
+				remaining = file.tasks.filter((item) => !item.done).length;
+			}
+		}
+		const kind = nextInjection(mode, framing, currentTaskId, statusKey);
+		if (!kind) return;
+		if (kind === "plan-framing") {
+			framing = rememberInjection(framing, kind);
+			return {
+				message: {
+					customType: PLAN_FRAMING_TYPE,
+					content: planPrompt(planSource),
+					display: false,
+					details: { phase: "plan" },
+				},
+			};
+		}
+		if (!task || !tasks || currentTaskId === undefined) return;
+		framing = rememberInjection(framing, kind, currentTaskId, statusKey);
+		if (kind === "build-framing") {
+			return {
+				message: {
+					customType: BUILD_FRAMING_TYPE,
+					content: buildPrompt(task, remaining, continueAll),
+					display: false,
+					details: { phase: "build", taskId: currentTaskId },
+				},
+			};
+		}
+		return {
+			message: {
+				customType: BUILD_STATUS_TYPE,
+				content: buildStatus(tasks, currentTaskId),
+				display: false,
+				details: { phase: "build", taskId: currentTaskId },
+			},
+		};
+	});
+
+	pi.on("context", async (event) => {
+		return { messages: filterFramingMessages(event.messages, mode) };
+	});
+
+	pi.on("tool_call", async (event, ctx) => {
+		if (mode !== "plan") return;
+		if (isToolCallEventType("bash", event)) {
+			if (!isSafePlanCommand(event.input.command)) {
+				return {
+					block: true,
+					reason: `Plan mode blocked this command. Use /build to implement.\nCommand: ${event.input.command}`,
+				};
+			}
+			return;
+		}
+		if (event.toolName === "write" || event.toolName === "edit") {
+			const path = pathFromInput(event.input);
+			if (!path || !isPlanArtifactPath(ctx.cwd, path)) {
+				return {
+					block: true,
+					reason: `Plan mode can only write ${planFilePath(ctx.cwd)} and ${taskFilePath(ctx.cwd)}.`,
+				};
+			}
+		}
+	});
+
+	pi.on("agent_settled", async (_event, ctx) => {
+		if (mode === "plan") {
+			const file = await loadTaskFile(ctx.cwd);
+			if (file && file.tasks.length > 0 && !planReadyNotified) {
+				planReadyNotified = true;
+				ctx.ui.notify(`Plan written. ${formatProgress(file.tasks)} tasks ready. Run /build to start.`, "info");
+			}
+			return;
+		}
+		await afterBuildSettled(ctx);
+	});
+}