pi-plans 0.1.2 → 0.3.0

package/src/plan.ts

@@ -35,6 +35,43 @@ export function scanDoneMarkers(text: string): string[] {
 	return [...text.matchAll(/\[DONE:(VC-\d+)\]/g)].map((match) => match[1]);
 }
 
+export interface CurrentIMarker {
+	id: string;
+}
+
+/** Extract current implementation-item anchors from an assistant message. */
+export function scanCurrentIMarkers(text: string): CurrentIMarker[] {
+	return [...text.matchAll(/\[(I-\d+):current\]/g)].map((match) => ({ id: match[1] }));
+}
+
+export const scanCurrentMarkers = scanCurrentIMarkers;
+
+/** Resolve the last known current-I marker, ignoring unknown ids. */
+export function resolveCurrentI(
+	implItems: ImplItem[],
+	markers: CurrentIMarker[] | string[],
+	fallback?: string,
+): string | undefined {
+	const known = new Set(implItems.map((item) => item.id));
+	let current: string | undefined;
+	for (const marker of markers) {
+		const id = typeof marker === "string" ? marker : marker.id;
+		if (known.has(id)) current = id;
+	}
+	return current ?? fallback;
+}
+
+/** Deterministic frontier used by snapshots written before currentI existed. */
+export function inferCurrentI(
+	implItems: ImplItem[] | undefined,
+	items: CheckItem[],
+	implStatus: Record<string, ImplMarkerState> | undefined,
+): string | undefined {
+	if (!implItems?.length) return undefined;
+	const statuses = resolveImplStatuses(implItems, items, implStatus);
+	return implItems.find((item) => statuses[item.id] !== "vc-passed")?.id ?? implItems.at(-1)?.id;
+}
+
 export type ImplMarkerState = "implemented" | "validating";
 
 export interface ImplMarker {

package/src/query-hook.ts

@@ -0,0 +1,82 @@
+import type { ExtensionAPI, ExtensionContext, InputEvent } from "@earendil-works/pi-coding-agent";
+
+export const QUERY_INTERVIEW_MESSAGE_CUSTOM_TYPE = "pi-plans-query-interview";
+export const QUERY_INTERVIEW_MESSAGE =
+	"Before implementing a new user request, if any requirement, constraint, expected behavior, or acceptance criterion is unclear, interview the user with focused clarification questions and confirm the answers before making changes. If the request is clear, proceed directly with the implementation.";
+
+interface QueryHookState {
+	pendingQueries: number;
+}
+
+type QueryHookSession = { __piPlansQueryHook?: QueryHookState };
+
+function sessionCarrier(ctx: ExtensionContext): QueryHookSession | undefined {
+	return ctx.sessionManager as unknown as QueryHookSession | undefined;
+}
+
+function ensureState(ctx: ExtensionContext): QueryHookState | undefined {
+	const session = sessionCarrier(ctx);
+	if (!session) return undefined;
+	return (session.__piPlansQueryHook ??= { pendingQueries: 0 });
+}
+
+export function isOrdinaryExternalQuery(
+	input: Pick<InputEvent, "text" | "source" | "streamingBehavior">,
+): boolean {
+	const text = input.text.trim();
+	return (
+		(input.source === "interactive" || input.source === "rpc")
+		&& input.streamingBehavior === undefined
+		&& text.length > 0
+		&& !text.startsWith("/")
+	);
+}
+
+export function recordOrdinaryQuery(
+	ctx: ExtensionContext,
+	input: Pick<InputEvent, "text" | "source" | "streamingBehavior">,
+): boolean {
+	if (!isOrdinaryExternalQuery(input)) return false;
+	const state = ensureState(ctx);
+	if (!state) return false;
+	state.pendingQueries += 1;
+	return true;
+}
+
+export function consumeOrdinaryQuery(ctx: ExtensionContext): boolean {
+	const session = sessionCarrier(ctx);
+	const state = session?.__piPlansQueryHook;
+	if (!state || state.pendingQueries <= 0) return false;
+	state.pendingQueries -= 1;
+	if (state.pendingQueries === 0) delete session.__piPlansQueryHook;
+	return true;
+}
+
+export function resetOrdinaryQueryState(ctx: ExtensionContext): void {
+	const session = sessionCarrier(ctx);
+	if (session) delete session.__piPlansQueryHook;
+}
+
+export function registerQueryInterviewHooks(
+	pi: ExtensionAPI,
+	suppressForWorkflow: (ctx: ExtensionContext) => boolean,
+): void {
+	pi.on("input", async (event, ctx) => {
+		recordOrdinaryQuery(ctx, event);
+	});
+
+	pi.on("before_agent_start", async (_event, ctx) => {
+		if (!consumeOrdinaryQuery(ctx) || suppressForWorkflow(ctx)) return;
+		return {
+			message: {
+				customType: QUERY_INTERVIEW_MESSAGE_CUSTOM_TYPE,
+				content: QUERY_INTERVIEW_MESSAGE,
+				display: false,
+			},
+		};
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		resetOrdinaryQueryState(ctx);
+	});
+}

package/src/refine-prompts.ts

@@ -30,6 +30,23 @@ Authority boundary: read-only analysis only. Do not edit, write, delete, commit,
 Evidence: inspect the repository with read, grep, find, and ls before judging the plan.${lensLine}${focusLine}${contextLine}`;
 }
 
+/** Shared header for the post-execution implementation review: the
+ * accepted plan is the contract, the IMPLEMENTATION in the worktree is
+ * under review. Findings must anchor to the plan's goals/acceptance
+ * criteria and explicitly assess delivery maturity. */
+function buildImplementationSharedHeader(role: "reviewer" | "criticizer", opts: RefinePromptInput): string {
+	const lensLine = role === "reviewer" && opts.lens ? `\nReview lens: ${opts.lens}.` : "";
+	const focusLine = opts.focus ? `\n\nSpecific concerns from the main agent: ${opts.focus}` : "";
+	const contextLine = opts.context ? `\n\nContext: ${opts.context}` : "";
+	return `Goal: ${role === "reviewer" ? "review the implemented result in the worktree against the plan" : "stress-test the implemented result's assumptions"}.
+
+Target: ${opts.planPath} (the accepted plan; the IMPLEMENTATION in the worktree is under review)
+
+Authority boundary: read-only analysis only. Do not edit, write, delete, commit, push, or spawn subagents.
+
+Evidence: inspect the repository with read, grep, find, and ls before judging the implementation. Judge the implementation against the plan's goals, verifier checklist, and acceptance criteria. Explicitly assess delivery maturity: did the executor ship a minimal MVP only, or refine for long-term growth (no stopgaps, long-term architectural decisions, missing tests, technical debt, production readiness)? Calibrate severity accordingly. Out-of-scope improvement ideas are low severity by default and must not be forced into findings.${lensLine}${focusLine}${contextLine}`;
+}
+
 export function reviewerLanes(count: number): ReviewerLane[] {
 	if (count === 3) return [...REVIEWER_LENSES];
 	if (count === 2) return [...REVIEWER_LENSES.slice(0, 2)];
@@ -68,3 +85,36 @@ Plan file: ${opts.planPath}
 ${opts.planText}
 ---8<--- END PLAN CONTENT ---8<---`;
 }
+
+export function buildImplementationReviewerTask(opts: RefinePromptInput): string {
+	return `${buildImplementationSharedHeader("reviewer", opts)}
+
+Success criteria: return evidence-backed findings or explicitly say the implementation holds up.
+
+Output: Markdown, highest severity first. For each finding use this shape:
+- \`F-###\` — severity: high | medium | low; affected plan IDs (e.g. R-001, I-003) or files; evidence: repo path/command that proves it; impact; recommended fix; suggested disposition (accept | reject | needs-discussion).
+
+Surface at most five high-priority findings; list lower-severity findings after them. If the implementation holds up, say so explicitly and list what you checked.
+
+Plan file: ${opts.planPath}
+
+---8<--- PLAN CONTENT ---8<---
+${opts.planText}
+---8<--- END PLAN CONTENT ---8<---`;
+}
+
+export function buildImplementationCriticizerTask(opts: RefinePromptInput): string {
+	return `${buildImplementationSharedHeader("criticizer", opts)}
+
+Success criteria: return concrete, answerable questions only; never rewrite the plan or the implementation.
+
+Output: Markdown in exactly this shape:
+1. A summary of your core criticism in at most three sentences, highlighting the single most important point.
+2. Then at most five adaptive questions, numbered, each with one line of why it matters. Questions must be answerable by a user with repo access — never rhetorical. Stop earlier if the implementation genuinely holds.
+
+Plan file: ${opts.planPath}
+
+---8<--- PLAN CONTENT ---8<---
+${opts.planText}
+---8<--- END PLAN CONTENT ---8<---`;
+}

package/src/refine-ui-helpers.ts

@@ -0,0 +1,142 @@
+/**
+ * Lightweight, dependency-free replacements for the pi-tui text utilities used
+ * by the refine overlay. Keeping these local lets the overlay render correctly
+ * in contexts where the pi-tui module is not on the resolver path (notably the
+ * standalone `node:test` runs in this repository, since `@earendil-works/pi-tui`
+ * is a peer of `@earendil-works/pi-coding-agent` rather than a direct
+ * dependency of pi-plans).
+ */
+
+const ELLIPSIS = "…";
+
+/**
+ * ECMA-48 CSI sequence: ESC [ parameter bytes (0x30-0x3F), intermediate bytes
+ * (0x20-0x2F), final byte (0x40-0x7E). Matched atomically so styling payloads
+ * never leak into width math and are never split mid-sequence.
+ */
+const CSI_PATTERN = /\x1b\[[\x30-\x3f]*[\x20-\x2f]*[\x40-\x7e]/g;
+
+interface AnsiPart {
+	kind: "csi" | "text";
+	value: string;
+}
+
+function splitAnsi(text: string): AnsiPart[] {
+	const parts: AnsiPart[] = [];
+	let last = 0;
+	for (const match of text.matchAll(CSI_PATTERN)) {
+		const start = match.index ?? 0;
+		if (start > last) parts.push({ kind: "text", value: text.slice(last, start) });
+		parts.push({ kind: "csi", value: match[0] });
+		last = start + match[0].length;
+	}
+	if (last < text.length) parts.push({ kind: "text", value: text.slice(last) });
+	return parts;
+}
+
+function graphemeWidth(text: string): number {
+	let width = 0;
+	for (const segment of new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(text)) {
+		const cp = segment.segment.codePointAt(0) ?? 0;
+		if (cp < 0x20) continue;
+		if (cp === 0x09) { width += 3; continue; }
+		if (cp >= 0x1100 && cp <= 0x115f) { width += 2; continue; }
+		if (cp >= 0x2e80 && cp <= 0x9fff) { width += 2; continue; }
+		if (cp >= 0xac00 && cp <= 0xd7a3) { width += 2; continue; }
+		if (cp >= 0xff00 && cp <= 0xff60) { width += 2; continue; }
+		if (cp >= 0x1f300 && cp <= 0x1faff) { width += 2; continue; }
+		width += 1;
+	}
+	return width;
+}
+
+export function visibleWidth(text: string): number {
+	if (!text) return 0;
+	let width = 0;
+	for (const part of splitAnsi(text)) {
+		if (part.kind === "csi") continue; // escape sequences render at zero width
+		width += graphemeWidth(part.value);
+	}
+	return width;
+}
+
+export function truncateToWidth(text: string, maxWidth: number, ellipsis = ELLIPSIS): string {
+	const measured = visibleWidth(text);
+	if (measured <= maxWidth) return text;
+	const ellipsisWidth = ellipsis ? visibleWidth(ellipsis) : 0;
+	const target = Math.max(0, maxWidth - ellipsisWidth);
+	let result = "";
+	let used = 0;
+	let exhausted = false;
+	for (const part of splitAnsi(text)) {
+		if (part.kind === "csi") {
+			if (!exhausted) result += part.value; // keep styling runs intact; never split them
+			continue;
+		}
+		for (const segment of new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(part.value)) {
+			const w = visibleWidth(segment.segment);
+			if (used + w > target) {
+				exhausted = true;
+				break;
+			}
+			result += segment.segment;
+			used += w;
+		}
+	}
+	// A kept open SGR (its reset lived past the cut) must not bleed into the
+	// ellipsis or anything rendered after this string.
+	if (exhausted && result.includes("\x1b[")) result += "\x1b[0m";
+	return ellipsis ? `${result}${ellipsis}` : result;
+}
+
+export function wrapTextWithAnsi(text: string, maxWidth: number): string[] {
+	if (maxWidth <= 0) return [text];
+	const normalized = text.replace(/\r\n/g, "\n");
+	const words = normalized.split(/(\s+)/);
+	const lines: string[] = [];
+	let current = "";
+	let currentWidth = 0;
+	for (const word of words) {
+		if (word === "") continue;
+		const wordWidth = visibleWidth(word);
+		if (wordWidth > maxWidth) {
+			// Hard split a single overlong word (ANSI-aware: CSI runs are zero-width and atomic).
+			if (current) { lines.push(current); current = ""; currentWidth = 0; }
+			let buffer = "";
+			let bufferWidth = 0;
+			for (const part of splitAnsi(word)) {
+				if (part.kind === "csi") {
+					buffer += part.value;
+					continue;
+				}
+				for (const segment of new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(part.value)) {
+					const w = visibleWidth(segment.segment);
+					if (bufferWidth + w > maxWidth) {
+						lines.push(buffer);
+						buffer = segment.segment;
+						bufferWidth = w;
+					} else {
+						buffer += segment.segment;
+						bufferWidth += w;
+					}
+				}
+			}
+			if (buffer) { lines.push(buffer); buffer = ""; bufferWidth = 0; }
+			continue;
+		}
+		if (currentWidth + wordWidth > maxWidth) {
+			lines.push(current.trimEnd());
+			current = word.trimStart();
+			currentWidth = visibleWidth(current);
+		} else {
+			current += word;
+			currentWidth += wordWidth;
+		}
+	}
+	if (current.trim().length > 0) lines.push(current.trimEnd());
+	return lines;
+}
+
+export function matchesEscape(data: string): boolean {
+	return data === "\x1b" || data === "\x1b\x1b" || /^(\x1b\[\??\d*[A-Za-z])|(\x1bO[A-Za-z])$/.test(data);
+}

package/src/refine-ui-state.ts

@@ -0,0 +1,144 @@
+import type { SubagentProgressEvent, SubagentResult } from "./subagent.ts";
+
+export type RefineOverlayRole = "reviewer" | "criticizer";
+export type RefineLaneStatus = "queued" | "running" | "complete" | "failed" | "cancelled";
+export type RefineTranscriptEntryType = "assistant-text" | "thinking" | "tool-call" | "tool-result" | "diagnostic";
+
+export interface RefineTranscriptEntry {
+	id: string;
+	type: RefineTranscriptEntryType;
+	text: string;
+	streaming: boolean;
+	toolCallId?: string;
+	toolName?: string;
+	isError?: boolean;
+}
+
+export interface RefineLaneState {
+	id: string;
+	label: string;
+	status: RefineLaneStatus;
+	phase: string;
+	detail: string;
+	transcript: RefineTranscriptEntry[];
+	currentTurnIndex: number;
+	scrollOffset: number;
+	followTranscript: boolean;
+	viewportHeight: number;
+}
+
+export function statusLabel(status: RefineLaneStatus): string {
+	switch (status) {
+		case "queued":
+			return "queued";
+		case "running":
+			return "running";
+		case "complete":
+			return "done";
+		case "failed":
+			return "failed";
+		case "cancelled":
+			return "cancelled";
+	}
+}
+
+function transcriptId(lane: RefineLaneState, event: Extract<SubagentProgressEvent, { type: "transcript" }>): string {
+	return `${lane.currentTurnIndex}:${event.key}`;
+}
+
+function phaseForEntry(event: Extract<SubagentProgressEvent, { type: "transcript" }>): string {
+	switch (event.entryType) {
+		case "assistant-text":
+			return "responding";
+		case "thinking":
+			return "thinking";
+		case "tool-call":
+			return event.toolName ? `tool: ${event.toolName}` : "tool call";
+		case "tool-result":
+			return event.toolName ? `result: ${event.toolName}` : "tool result";
+		case "diagnostic":
+			return "diagnostic";
+	}
+}
+
+function applyTranscriptEvent(lane: RefineLaneState, event: Extract<SubagentProgressEvent, { type: "transcript" }>): void {
+	const id = transcriptId(lane, event);
+	let entry = lane.transcript.find((candidate) => candidate.id === id);
+	if (!entry && event.entryType === "tool-call" && event.toolCallId) {
+		entry = lane.transcript.find((candidate) => candidate.type === "tool-call" && candidate.toolCallId === event.toolCallId);
+	}
+	if (!entry) {
+		entry = { id, type: event.entryType, text: "", streaming: event.streaming };
+		lane.transcript.push(entry);
+	}
+	if (event.update === "append") entry.text += event.text;
+	else entry.text = event.text;
+	entry.streaming = event.streaming;
+	if (event.toolCallId !== undefined) entry.toolCallId = event.toolCallId;
+	if (event.toolName !== undefined) entry.toolName = event.toolName;
+	if (event.isError !== undefined) entry.isError = event.isError;
+	lane.detail = entry.text;
+	lane.status = "running";
+	lane.phase = phaseForEntry(event);
+}
+
+function applyDiagnostic(lane: RefineLaneState, text: string): void {
+	if (!text) return;
+	const id = `${lane.currentTurnIndex}:diagnostic`;
+	const existing = lane.transcript.find((entry) => entry.id === id);
+	if (existing) existing.text += text;
+	else lane.transcript.push({ id, type: "diagnostic", text, streaming: true });
+	lane.detail = text;
+	lane.phase = "diagnostic";
+}
+
+export function applyRefineProgress(lane: RefineLaneState, event: SubagentProgressEvent): void {
+	if (lane.status === "complete" || lane.status === "failed" || lane.status === "cancelled") return;
+
+	switch (event.type) {
+		case "process":
+			lane.phase = event.phase === "started" ? "starting" : "exiting";
+			return;
+		case "turn":
+			if (event.phase === "start") {
+				lane.status = "running";
+				lane.phase = "thinking";
+				lane.currentTurnIndex = event.turnIndex ?? lane.currentTurnIndex + 1;
+			} else {
+				lane.phase = "waiting";
+			}
+			return;
+		case "transcript":
+			applyTranscriptEvent(lane, event);
+			return;
+		case "stderr":
+			applyDiagnostic(lane, event.text);
+			return;
+	}
+}
+
+export function applyRefineResult(lane: RefineLaneState, result: SubagentResult): void {
+	const finalText = result.output || result.errorMessage || result.stderr || "";
+	const finalEntry = [...lane.transcript].reverse().find((entry) => entry.type === "assistant-text");
+	if (finalText) {
+		if (finalEntry) {
+			finalEntry.text = finalText;
+			finalEntry.streaming = false;
+		} else {
+			lane.transcript.push({ id: `${lane.currentTurnIndex}:result`, type: "assistant-text", text: finalText, streaming: false });
+		}
+	}
+	lane.detail = finalText;
+	if (result.ok) {
+		lane.status = "complete";
+		lane.phase = "complete";
+		return;
+	}
+	if (result.cancelled) {
+		lane.status = "cancelled";
+		lane.phase = "cancelled";
+		return;
+	}
+	lane.status = "failed";
+	lane.phase = result.timedOut ? "timed out" : "failed";
+}