@diegopetrucci/pi-annotate-last-message 0.1.0

package/.pi-fleet-tested-version

@@ -0,0 +1 @@
+0.78.0

package/README.md

@@ -0,0 +1,40 @@
+# annotate-last-message
+
+A standalone pi extension that adds `/annotate-last-message`, a native Glimpse window for annotating the latest completed assistant message on the current session branch.
+
+## Install
+
+```bash
+pi install npm:@diegopetrucci/pi-annotate-last-message
+```
+
+Then reload pi:
+
+```text
+/reload
+```
+
+## Usage
+
+Run `/annotate-last-message` from an interactive pi session. The annotation window lets you leave:
+
+- overall guidance for the whole reply,
+- section comments for larger chunks of the message, and
+- inline notes tied to individual lines.
+
+When you submit, the extension appends a structured planning-oriented feedback prompt to the current editor buffer. It does not auto-apply changes or rewrite the previous assistant message in place.
+
+## Requirements
+
+- Interactive pi session with editor access.
+- A completed assistant message with text on the active branch.
+- Local desktop support for opening a native [Glimpse](https://github.com/mariozechner/glimpse) window.
+
+## Troubleshooting
+
+- `annotate-last-message requires interactive mode.` → run it from the pi TUI.
+- `No assistant messages found on the current session branch.` → wait for an assistant reply, then rerun.
+- `Latest assistant message is incomplete (...)` → wait for the assistant turn to finish, then rerun.
+- `Latest assistant message has no text to annotate.` → rerun after a normal text reply.
+- `A last-message annotation window is already open.` → reuse or close the existing window before opening another.
+- `Annotation failed: Glimpse host not found ...` → the native window runtime is unavailable; reinstall/update the package and rerun from a machine/session that can open native windows.

package/glimpseui.d.ts

@@ -0,0 +1,89 @@
+declare module "glimpseui" {
+	import { EventEmitter } from "node:events";
+
+	export type FollowMode = "snap" | "spring";
+	export type CursorAnchor = "top-left" | "top-right" | "right" | "bottom-right" | "bottom-left" | "left";
+
+	export interface GlimpseOpenOptions {
+		width?: number;
+		height?: number;
+		title?: string;
+		x?: number;
+		y?: number;
+		frameless?: boolean;
+		floating?: boolean;
+		transparent?: boolean;
+		clickThrough?: boolean;
+		followCursor?: boolean;
+		followMode?: FollowMode;
+		cursorAnchor?: CursorAnchor;
+		cursorOffset?: {
+			x?: number;
+			y?: number;
+		};
+		hidden?: boolean;
+		autoClose?: boolean;
+		timeout?: number;
+	}
+
+	export interface GlimpseScreenInfo {
+		width: number;
+		height: number;
+		scaleFactor: number;
+		visibleX?: number;
+		visibleY?: number;
+		visibleWidth?: number;
+		visibleHeight?: number;
+		x?: number;
+		y?: number;
+	}
+
+	export interface GlimpseAppearanceInfo {
+		darkMode: boolean;
+		accentColor: string;
+		reduceMotion: boolean;
+		increaseContrast: boolean;
+	}
+
+	export interface GlimpseCursorInfo {
+		x: number;
+		y: number;
+	}
+
+	export interface GlimpseCursorTip {
+		x: number;
+		y: number;
+	}
+
+	export interface GlimpseInfo {
+		screen: GlimpseScreenInfo;
+		screens: GlimpseScreenInfo[];
+		appearance: GlimpseAppearanceInfo;
+		cursor: GlimpseCursorInfo;
+		cursorTip: GlimpseCursorTip | null;
+	}
+
+	export class GlimpseWindow extends EventEmitter {
+		on(event: "ready", listener: (info: GlimpseInfo) => void): this;
+		on(event: "message", listener: (data: unknown) => void): this;
+		on(event: "info", listener: (info: GlimpseInfo) => void): this;
+		on(event: "closed", listener: () => void): this;
+		on(event: "error", listener: (error: Error) => void): this;
+		once(event: "ready", listener: (info: GlimpseInfo) => void): this;
+		once(event: "message", listener: (data: unknown) => void): this;
+		once(event: "info", listener: (info: GlimpseInfo) => void): this;
+		once(event: "closed", listener: () => void): this;
+		once(event: "error", listener: (error: Error) => void): this;
+		send(js: string): void;
+		setHTML(html: string): void;
+		show(options?: { title?: string }): void;
+		close(): void;
+		loadFile(path: string): void;
+		get info(): GlimpseInfo | null;
+		getInfo(): void;
+		followCursor(enabled: boolean, anchor?: CursorAnchor, mode?: FollowMode): void;
+	}
+
+	export function open(html: string, options?: GlimpseOpenOptions): GlimpseWindow;
+	export function prompt<T = unknown>(html: string, options?: GlimpseOpenOptions): Promise<T | null>;
+}

package/index.ts

@@ -0,0 +1,165 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+import { openQuietGlimpse, type QuietGlimpseWindow } from "./quiet-glimpse.js";
+import { composeAnnotateLastMessagePrompt, hasAnnotateLastMessageFeedback } from "./prompt.js";
+import { findLastAssistantMessage } from "./session.js";
+import type { AnnotateLastMessageCancelPayload, AnnotateLastMessageSubmitPayload, AnnotateLastMessageWindowMessage, LastAssistantMessageData } from "./types.js";
+import { buildAnnotateLastMessageHtml } from "./ui.js";
+
+function isSubmitPayload(value: unknown): value is AnnotateLastMessageSubmitPayload {
+	return typeof value === "object" && value != null && "type" in value && value.type === "submit";
+}
+
+function isCancelPayload(value: unknown): value is AnnotateLastMessageCancelPayload {
+	return typeof value === "object" && value != null && "type" in value && value.type === "cancel";
+}
+
+function appendPrompt(ctx: ExtensionCommandContext, prompt: string): void {
+	const prefix = ctx.ui.getEditorText().trim().length > 0 ? "\n\n" : "";
+	ctx.ui.pasteToEditor(`${prefix}${prompt}`);
+}
+
+export function registerAnnotateLastMessageCommand(pi: ExtensionAPI): void {
+	let activeWindow: QuietGlimpseWindow | null = null;
+	const suppressedWindows = new WeakSet<QuietGlimpseWindow>();
+
+	function closeActiveWindow(options: { suppressResults?: boolean } = {}): void {
+		if (activeWindow == null) return;
+		const windowToClose = activeWindow;
+		activeWindow = null;
+		if (options.suppressResults) {
+			suppressedWindows.add(windowToClose);
+		}
+		try {
+			windowToClose.close();
+		} catch {
+			// Ignore races when the native window is already closing.
+		}
+	}
+
+	async function openAnnotationWindow(ctx: ExtensionCommandContext): Promise<void> {
+		if (!ctx.hasUI) {
+			ctx.ui.notify("annotate-last-message requires interactive mode.", "error");
+			return;
+		}
+		if (activeWindow != null) {
+			ctx.ui.notify("A last-message annotation window is already open.", "warning");
+			return;
+		}
+
+		const messageResult = findLastAssistantMessage(ctx.sessionManager.getBranch());
+		if (!messageResult.ok) {
+			ctx.ui.notify(messageResult.message, "error");
+			return;
+		}
+
+		const messageData = messageResult.data;
+
+		try {
+			const html = buildAnnotateLastMessageHtml(messageData);
+			const window = await openQuietGlimpse(html, {
+				width: 1440,
+				height: 980,
+				title: "annotate last message",
+			});
+			activeWindow = window;
+
+			const terminalMessagePromise = new Promise<AnnotateLastMessageSubmitPayload | AnnotateLastMessageCancelPayload | null>(
+				(resolve, reject) => {
+					let settled = false;
+					let closeTimer: ReturnType<typeof setTimeout> | null = null;
+
+					const cleanup = (): void => {
+						if (closeTimer != null) {
+							clearTimeout(closeTimer);
+							closeTimer = null;
+						}
+						window.removeListener("message", onMessage);
+						window.removeListener("closed", onClosed);
+						window.removeListener("error", onError);
+						if (activeWindow === window) {
+							activeWindow = null;
+						}
+					};
+
+					const settle = (value: AnnotateLastMessageWindowMessage | null): void => {
+						if (settled) return;
+						settled = true;
+						cleanup();
+						resolve(value);
+					};
+
+					const onMessage = (data: unknown): void => {
+						if (isSubmitPayload(data) || isCancelPayload(data)) {
+							settle(data);
+						}
+					};
+
+					const onClosed = (): void => {
+						if (settled || closeTimer != null) return;
+						closeTimer = setTimeout(() => {
+							closeTimer = null;
+							settle(null);
+						}, 250);
+					};
+
+					const onError = (error: Error): void => {
+						if (settled) return;
+						settled = true;
+						cleanup();
+						reject(error);
+					};
+
+					window.on("message", onMessage);
+					window.on("closed", onClosed);
+					window.on("error", onError);
+				},
+			);
+
+			void (async (windowMessageSource: QuietGlimpseWindow, sourceData: LastAssistantMessageData) => {
+				try {
+					const result = await terminalMessagePromise;
+					if (suppressedWindows.has(windowMessageSource)) return;
+					if (result == null) return;
+					if (result.type === "cancel") {
+						ctx.ui.notify("Annotation cancelled.", "info");
+						return;
+					}
+					if (!hasAnnotateLastMessageFeedback(result)) {
+						ctx.ui.notify("No annotation feedback submitted.", "info");
+						return;
+					}
+
+					const prompt = composeAnnotateLastMessagePrompt(sourceData, result);
+					appendPrompt(ctx, prompt);
+					ctx.ui.notify("Appended annotation feedback to the editor.", "info");
+				} catch (error) {
+					if (suppressedWindows.has(windowMessageSource)) return;
+					const message = error instanceof Error ? error.message : String(error);
+					ctx.ui.notify(`Annotation failed: ${message}`, "error");
+				}
+			})(window, messageData);
+
+			ctx.ui.notify("Opened native annotation window.", "info");
+		} catch (error) {
+			closeActiveWindow({ suppressResults: true });
+			const message = error instanceof Error ? error.message : String(error);
+			ctx.ui.notify(`Annotation failed: ${message}`, "error");
+		}
+	}
+
+	pi.registerCommand("annotate-last-message", {
+		description: "Open a native annotation window for the latest assistant message",
+		handler: async (_args, ctx) => {
+			await openAnnotationWindow(ctx);
+		},
+	});
+
+	pi.on("session_shutdown", async () => {
+		closeActiveWindow({ suppressResults: true });
+	});
+}
+
+export default function (pi: ExtensionAPI): void {
+	registerAnnotateLastMessageCommand(pi);
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@diegopetrucci/pi-annotate-last-message",
+  "version": "0.1.0",
+  "description": "A standalone pi extension that adds /annotate-last-message, a native Glimpse UI for annotating the latest assistant reply.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "annotate",
+    "feedback",
+    "assistant-message"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/diegopetrucci/pi-extensions.git",
+    "directory": "extensions/annotate-last-message"
+  },
+  "files": [
+    "index.ts",
+    "prompt.ts",
+    "quiet-glimpse.ts",
+    "session.ts",
+    "types.ts",
+    "ui.ts",
+    "web",
+    "glimpseui.d.ts",
+    "README.md",
+    ".pi-fleet-tested-version"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "dependencies": {
+    "glimpseui": "^0.8.1"
+  },
+  "type": "module"
+}

package/prompt.ts

@@ -0,0 +1,93 @@
+import type { AnnotateLastMessageInlineComment, AnnotateLastMessageSectionComment, AnnotateLastMessageSubmitPayload, LastAssistantMessageData, LastAssistantMessageLine, LastAssistantMessageSection } from "./types.js";
+
+const EXCERPT_LIMIT = 120;
+
+function truncateExcerpt(value: string, limit = EXCERPT_LIMIT): string {
+	const normalized = value.replace(/\s+/g, " ").trim();
+	if (normalized.length === 0) return "(blank line)";
+	if (normalized.length <= limit) return normalized;
+	return `${normalized.slice(0, Math.max(0, limit - 1)).trimEnd()}…`;
+}
+
+function formatLineLabel(line: number): string {
+	return `line ${line}`;
+}
+
+function formatLineComment(comment: AnnotateLastMessageInlineComment, line: LastAssistantMessageLine | undefined): string {
+	const excerpt = truncateExcerpt(line?.text ?? "");
+	return `${formatLineLabel(comment.line)} — “${excerpt}”`;
+}
+
+function formatSectionLineRange(section: LastAssistantMessageSection): string {
+	return section.startLine === section.endLine
+		? `line ${section.startLine}`
+		: `lines ${section.startLine}-${section.endLine}`;
+}
+
+function formatSectionComment(comment: AnnotateLastMessageSectionComment, section: LastAssistantMessageSection | undefined): string {
+	if (section == null) {
+		return "Unknown section";
+	}
+	return `Section ${section.index} (${formatSectionLineRange(section)}) — “${truncateExcerpt(section.preview)}”`;
+}
+
+export function hasAnnotateLastMessageFeedback(payload: AnnotateLastMessageSubmitPayload): boolean {
+	if (payload.overallComment.trim().length > 0) {
+		return true;
+	}
+	if (payload.inlineComments.some((comment) => comment.body.trim().length > 0)) {
+		return true;
+	}
+	return payload.sectionComments.some((comment) => comment.body.trim().length > 0);
+}
+
+export function composeAnnotateLastMessagePrompt(
+	message: LastAssistantMessageData,
+	payload: AnnotateLastMessageSubmitPayload,
+): string {
+	const lineMap = new Map(message.lines.map((line) => [line.number, line]));
+	const sectionMap = new Map(message.sections.map((section) => [section.id, section]));
+	const inlineComments = payload.inlineComments
+		.filter((comment) => comment.body.trim().length > 0)
+		.sort((left, right) => left.line - right.line);
+	const sectionComments = payload.sectionComments
+		.filter((comment) => comment.body.trim().length > 0)
+		.sort((left, right) => (sectionMap.get(left.sectionId)?.index ?? Number.MAX_SAFE_INTEGER) - (sectionMap.get(right.sectionId)?.index ?? Number.MAX_SAFE_INTEGER));
+	const lines: string[] = [];
+
+	lines.push("Please revisit your last assistant message using the annotation feedback below.");
+	lines.push("");
+	lines.push("Treat this as planning-oriented feedback:");
+	lines.push("- update your explanation, plan, or proposed approach in chat;");
+	lines.push("- do not assume any code or file changes have already been applied;");
+	lines.push("- do not auto-apply anything outside the normal response flow.");
+	lines.push("");
+
+	const overallComment = payload.overallComment.trim();
+	if (overallComment.length > 0) {
+		lines.push("## Overall guidance");
+		lines.push(overallComment);
+		lines.push("");
+	}
+
+	if (sectionComments.length > 0) {
+		lines.push("## Section comments");
+		sectionComments.forEach((comment, index) => {
+			lines.push(`${index + 1}. ${formatSectionComment(comment, sectionMap.get(comment.sectionId))}`);
+			lines.push(`   ${comment.body.trim()}`);
+			lines.push("");
+		});
+	}
+
+	if (inlineComments.length > 0) {
+		lines.push("## Inline comments");
+		inlineComments.forEach((comment, index) => {
+			lines.push(`${index + 1}. ${formatLineComment(comment, lineMap.get(comment.line))}`);
+			lines.push(`   ${comment.body.trim()}`);
+			lines.push("");
+		});
+	}
+
+	lines.push("Please respond by revising your last message or its plan in chat, incorporating the feedback above.");
+	return lines.join("\n").trim();
+}

package/quiet-glimpse.ts

@@ -0,0 +1,156 @@
+/// <reference path="./glimpseui.d.ts" />
+
+import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { existsSync } from "node:fs";
+import { createInterface } from "node:readline";
+import type { GlimpseOpenOptions } from "glimpseui";
+
+interface NativeHostInfo {
+	path: string;
+	extraArgs?: string[];
+	buildHint?: string;
+}
+
+interface GlimpseProtocolMessage {
+	type?: string;
+	data?: unknown;
+	screen?: unknown;
+	screens?: unknown;
+	appearance?: unknown;
+	cursor?: unknown;
+	cursorTip?: unknown;
+}
+
+export interface QuietGlimpseWindow {
+	on(event: "message", listener: (data: unknown) => void): this;
+	on(event: "closed", listener: () => void): this;
+	on(event: "error", listener: (error: Error) => void): this;
+	removeListener(event: "message", listener: (data: unknown) => void): this;
+	removeListener(event: "closed", listener: () => void): this;
+	removeListener(event: "error", listener: (error: Error) => void): this;
+	send(js: string): void;
+	close(): void;
+}
+
+class QuietGlimpseWindowImpl extends EventEmitter implements QuietGlimpseWindow {
+	#proc: ChildProcessWithoutNullStreams;
+	#closed = false;
+	#pendingHTML: string | null;
+	#stderr = "";
+
+	constructor(proc: ChildProcessWithoutNullStreams, initialHTML: string) {
+		super();
+		this.#proc = proc;
+		this.#pendingHTML = initialHTML;
+
+		proc.stdin.on("error", () => {});
+		proc.stderr.on("data", (chunk) => {
+			this.#stderr += chunk.toString();
+		});
+
+		const rl = createInterface({ input: proc.stdout, crlfDelay: Infinity });
+		rl.on("line", (line) => {
+			let message: GlimpseProtocolMessage;
+			try {
+				message = JSON.parse(line) as GlimpseProtocolMessage;
+			} catch {
+				this.emit("error", new Error(`Malformed glimpse protocol line: ${line}`));
+				return;
+			}
+
+			switch (message.type) {
+				case "ready":
+					if (this.#pendingHTML != null) {
+						this.setHTML(this.#pendingHTML);
+						this.#pendingHTML = null;
+					}
+					break;
+				case "message":
+					this.emit("message", message.data);
+					break;
+				case "closed":
+					this.#markClosed();
+					break;
+				default:
+					break;
+			}
+		});
+
+		proc.on("error", (error) => this.emit("error", error));
+		proc.on("exit", (code, signal) => {
+			const stderr = this.#stderr.trim();
+			const failed = signal != null || (code != null && code !== 0);
+			if (!this.#closed && failed) {
+				const message = stderr || `Glimpse process exited abnormally (code: ${code}, signal: ${signal}).`;
+				this.emit("error", new Error(message));
+			}
+			this.#markClosed();
+		});
+	}
+
+	send(js: string): void {
+		this.#write({ type: "eval", js });
+	}
+
+	close(): void {
+		this.#write({ type: "close" });
+	}
+
+	#markClosed(): void {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.emit("closed");
+	}
+
+	#write(obj: Record<string, unknown>): void {
+		if (this.#closed) return;
+		this.#proc.stdin.write(`${JSON.stringify(obj)}\n`);
+	}
+
+	setHTML(html: string): void {
+		this.#write({ type: "html", html: Buffer.from(html).toString("base64") });
+	}
+}
+
+async function getNativeHostInfo(): Promise<NativeHostInfo> {
+	const glimpseModule = (await import("glimpseui")) as unknown as { getNativeHostInfo: () => NativeHostInfo };
+	return glimpseModule.getNativeHostInfo();
+}
+
+export async function openQuietGlimpse(html: string, options: GlimpseOpenOptions = {}): Promise<QuietGlimpseWindow> {
+	const host = await getNativeHostInfo();
+	if (!existsSync(host.path)) {
+		const hint = host.buildHint ? ` ${host.buildHint}` : "";
+		throw new Error(`Glimpse host not found at '${host.path}'.${hint}`);
+	}
+	const args: string[] = [];
+
+	if (options.width != null) args.push("--width", String(options.width));
+	if (options.height != null) args.push("--height", String(options.height));
+	if (options.title != null) args.push("--title", options.title);
+	if (options.frameless) args.push("--frameless");
+	if (options.floating) args.push("--floating");
+	if (options.transparent) args.push("--transparent");
+	if (options.clickThrough) args.push("--click-through");
+	if (options.hidden) args.push("--hidden");
+	if (options.autoClose) args.push("--auto-close");
+	if (options.x != null) args.push(`--x=${options.x}`);
+	if (options.y != null) args.push(`--y=${options.y}`);
+	if (options.cursorOffset?.x != null) args.push(`--cursor-offset-x=${options.cursorOffset.x}`);
+	if (options.cursorOffset?.y != null) args.push(`--cursor-offset-y=${options.cursorOffset.y}`);
+	if (options.cursorAnchor != null) args.push("--cursor-anchor", options.cursorAnchor);
+	if (options.followMode != null) args.push("--follow-mode", options.followMode);
+	if (options.followCursor) args.push("--follow-cursor");
+
+	const proc = spawn(host.path, [...(host.extraArgs ?? []), ...args], {
+		stdio: ["pipe", "pipe", "pipe"],
+		windowsHide: process.platform === "win32",
+		env: {
+			...process.env,
+			OS_ACTIVITY_MODE: process.env.OS_ACTIVITY_MODE ?? "disable",
+		},
+	});
+
+	return new QuietGlimpseWindowImpl(proc, html);
+}

package/session.ts

@@ -0,0 +1,112 @@
+import type { SessionEntry, SessionMessageEntry } from "@earendil-works/pi-coding-agent";
+
+import type { LastAssistantMessageData, LastAssistantMessageLookupResult, LastAssistantMessageSection } from "./types.js";
+
+const SECTION_PREVIEW_LIMIT = 96;
+
+function truncatePreview(value: string, limit = SECTION_PREVIEW_LIMIT): string {
+	const normalized = value.replace(/\s+/g, " ").trim();
+	if (normalized.length <= limit) return normalized;
+	return `${normalized.slice(0, Math.max(0, limit - 1)).trimEnd()}…`;
+}
+
+function assistantMessageText(
+	messageEntry: SessionMessageEntry,
+): { kind: "assistant"; text: string } | { kind: "incomplete"; stopReason: string } | null {
+	const { message } = messageEntry;
+	if (!("role" in message) || message.role !== "assistant") {
+		return null;
+	}
+	if (message.stopReason !== "stop") {
+		return { kind: "incomplete", stopReason: String(message.stopReason) };
+	}
+	if (!Array.isArray(message.content)) {
+		return { kind: "assistant", text: "" };
+	}
+	return {
+		kind: "assistant",
+		text: message.content
+			.filter((part): part is { type: "text"; text: string } => part.type === "text" && typeof part.text === "string")
+			.map((part) => part.text)
+			.join("\n")
+			.replace(/\r\n?/g, "\n"),
+	};
+}
+
+function buildSections(lines: string[]): LastAssistantMessageSection[] {
+	const sections: LastAssistantMessageSection[] = [];
+	let startIndex: number | null = null;
+
+	const flushSection = (endIndex: number): void => {
+		if (startIndex == null) return;
+		const sectionLines = lines.slice(startIndex, endIndex + 1);
+		const previewSource = sectionLines.find((line) => line.trim().length > 0) ?? "";
+		sections.push({
+			id: `section-${sections.length + 1}`,
+			index: sections.length + 1,
+			startLine: startIndex + 1,
+			endLine: endIndex + 1,
+			preview: truncatePreview(previewSource),
+			text: sectionLines.join("\n"),
+		});
+		startIndex = null;
+	};
+
+	for (let index = 0; index < lines.length; index += 1) {
+		const line = lines[index];
+		if (line.trim().length === 0) {
+			flushSection(index - 1);
+			continue;
+		}
+		if (startIndex == null) {
+			startIndex = index;
+		}
+	}
+
+	flushSection(lines.length - 1);
+	return sections;
+}
+
+export function findLastAssistantMessage(branch: SessionEntry[]): LastAssistantMessageLookupResult {
+	for (let index = branch.length - 1; index >= 0; index -= 1) {
+		const entry = branch[index];
+		if (entry.type !== "message") {
+			continue;
+		}
+		const extracted = assistantMessageText(entry);
+		if (extracted == null) {
+			continue;
+		}
+		if (extracted.kind === "incomplete") {
+			return {
+				ok: false,
+				code: "incomplete",
+				message: `Latest assistant message is incomplete (${extracted.stopReason}). Wait for it to finish, then try again.`,
+			};
+		}
+
+		const text = extracted.text;
+		const trimmed = text.trim();
+		if (trimmed.length === 0) {
+			return {
+				ok: false,
+				code: "empty",
+				message: "Latest assistant message has no text to annotate.",
+			};
+		}
+
+		const lines = text.split("\n");
+		const data: LastAssistantMessageData = {
+			text,
+			lines: lines.map((line, lineIndex) => ({ number: lineIndex + 1, text: line })),
+			sections: buildSections(lines),
+		};
+		return { ok: true, data };
+	}
+
+	return {
+		ok: false,
+		code: "missing",
+		message: "No assistant messages found on the current session branch.",
+	};
+}

package/types.ts

@@ -0,0 +1,46 @@
+export interface LastAssistantMessageLine {
+	number: number;
+	text: string;
+}
+
+export interface LastAssistantMessageSection {
+	id: string;
+	index: number;
+	startLine: number;
+	endLine: number;
+	preview: string;
+	text: string;
+}
+
+export interface LastAssistantMessageData {
+	text: string;
+	lines: LastAssistantMessageLine[];
+	sections: LastAssistantMessageSection[];
+}
+
+export type LastAssistantMessageLookupResult =
+	| { ok: true; data: LastAssistantMessageData }
+	| { ok: false; code: "missing" | "incomplete" | "empty"; message: string };
+
+export interface AnnotateLastMessageInlineComment {
+	line: number;
+	body: string;
+}
+
+export interface AnnotateLastMessageSectionComment {
+	sectionId: string;
+	body: string;
+}
+
+export interface AnnotateLastMessageSubmitPayload {
+	type: "submit";
+	overallComment: string;
+	inlineComments: AnnotateLastMessageInlineComment[];
+	sectionComments: AnnotateLastMessageSectionComment[];
+}
+
+export interface AnnotateLastMessageCancelPayload {
+	type: "cancel";
+}
+
+export type AnnotateLastMessageWindowMessage = AnnotateLastMessageSubmitPayload | AnnotateLastMessageCancelPayload;

package/ui.ts

@@ -0,0 +1,23 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { LastAssistantMessageData } from "./types.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const webDir = join(__dirname, "web");
+
+function escapeForInlineScript(value: string): string {
+	return value.replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/&/g, "\\u0026");
+}
+
+function escapeInlineScriptSource(value: string): string {
+	return value.replace(/<\/(script)/gi, "<\\/$1");
+}
+
+export function buildAnnotateLastMessageHtml(data: LastAssistantMessageData): string {
+	const templateHtml = readFileSync(join(webDir, "index.html"), "utf8");
+	const appJs = escapeInlineScriptSource(readFileSync(join(webDir, "app.js"), "utf8"));
+	const payload = escapeForInlineScript(JSON.stringify(data));
+	return templateHtml.replace('"__INLINE_DATA__"', payload).replace("__INLINE_JS__", appJs);
+}

package/web/app.js

@@ -0,0 +1,229 @@
+/* global window, document */
+
+const messageData = JSON.parse(document.getElementById("annotate-last-message-data").textContent || "{}");
+
+if (!Array.isArray(messageData.lines)) messageData.lines = [];
+if (!Array.isArray(messageData.sections)) messageData.sections = [];
+
+const state = {
+	overallComment: "",
+	inlineComments: new Map(),
+	sectionComments: new Map(),
+};
+
+const elements = {
+	messageLines: document.getElementById("message-lines"),
+	overallComment: document.getElementById("overall-comment"),
+	sectionComments: document.getElementById("section-comments"),
+	status: document.getElementById("status"),
+	submitButton: document.getElementById("submit-button"),
+	cancelButton: document.getElementById("cancel-button"),
+};
+
+function feedbackCount() {
+	let count = state.overallComment.trim().length > 0 ? 1 : 0;
+	for (const value of state.inlineComments.values()) {
+		if (value.trim().length > 0) count += 1;
+	}
+	for (const value of state.sectionComments.values()) {
+		if (value.trim().length > 0) count += 1;
+	}
+	return count;
+}
+
+function setStatus(message, status = "idle") {
+	elements.status.textContent = message;
+	elements.status.dataset.state = status;
+}
+
+function updateSubmitState() {
+	const count = feedbackCount();
+	elements.submitButton.disabled = count === 0;
+	if (count === 0) {
+		setStatus("Add any feedback you want to send back to the editor.");
+		return;
+	}
+	const noun = count === 1 ? "item" : "items";
+	setStatus(`Ready to submit ${count} feedback ${noun}.`, "ready");
+}
+
+function setInlineComment(lineNumber, value) {
+	state.inlineComments.set(lineNumber, value);
+	updateSubmitState();
+}
+
+function setSectionComment(sectionId, value) {
+	state.sectionComments.set(sectionId, value);
+	updateSubmitState();
+}
+
+function createInlineEditor(line) {
+	const container = document.createElement("div");
+	container.className = "inline-editor";
+	container.hidden = true;
+
+	const meta = document.createElement("p");
+	meta.className = "line-meta";
+	meta.textContent = `Inline note for line ${line.number}`;
+	container.append(meta);
+
+	const textarea = document.createElement("textarea");
+	textarea.placeholder = "Explain what should change here, what is unclear, or what planning detail is missing.";
+	textarea.value = state.inlineComments.get(line.number) || "";
+	container.append(textarea);
+
+	return { container, textarea };
+}
+
+function createLineRow(line) {
+	const wrapper = document.createElement("div");
+	wrapper.className = "message-line";
+
+	const row = document.createElement("div");
+	row.className = "message-line-row";
+
+	const lineNumber = document.createElement("div");
+	lineNumber.className = "line-number";
+	lineNumber.textContent = String(line.number);
+	row.append(lineNumber);
+
+	const lineText = document.createElement("pre");
+	lineText.className = "line-text";
+	lineText.textContent = line.text.length > 0 ? line.text : " ";
+	row.append(lineText);
+
+	const toggle = document.createElement("button");
+	toggle.className = "inline-toggle";
+	toggle.type = "button";
+	toggle.textContent = "Add inline note";
+	row.append(toggle);
+
+	const editor = createInlineEditor(line);
+	const syncToggle = () => {
+		const hasValue = (state.inlineComments.get(line.number) || "").trim().length > 0;
+		toggle.dataset.active = hasValue || !editor.container.hidden ? "true" : "false";
+		toggle.textContent = hasValue ? "Edit inline note" : "Add inline note";
+	};
+
+	editor.textarea.addEventListener("input", () => {
+		setInlineComment(line.number, editor.textarea.value);
+		syncToggle();
+	});
+
+	toggle.addEventListener("click", () => {
+		editor.container.hidden = !editor.container.hidden;
+		syncToggle();
+		if (!editor.container.hidden) {
+			editor.textarea.focus();
+		}
+	});
+
+	wrapper.append(row);
+	wrapper.append(editor.container);
+	syncToggle();
+	return wrapper;
+}
+
+function createSectionCard(section) {
+	const card = document.createElement("div");
+	card.className = "section-card";
+
+	const title = document.createElement("h3");
+	const lineRange = section.startLine === section.endLine
+		? `line ${section.startLine}`
+		: `lines ${section.startLine}-${section.endLine}`;
+	title.textContent = `Section ${section.index}`;
+	card.append(title);
+
+	const meta = document.createElement("p");
+	meta.className = "section-meta";
+	meta.textContent = lineRange;
+	card.append(meta);
+
+	const preview = document.createElement("div");
+	preview.className = "section-preview";
+	preview.textContent = section.text;
+	card.append(preview);
+
+	const textarea = document.createElement("textarea");
+	textarea.placeholder = "Describe what should change across this section or what larger concern should be addressed.";
+	textarea.value = state.sectionComments.get(section.id) || "";
+	textarea.addEventListener("input", () => {
+		setSectionComment(section.id, textarea.value);
+	});
+	card.append(textarea);
+
+	return card;
+}
+
+function renderMessageLines() {
+	elements.messageLines.replaceChildren();
+	for (const line of messageData.lines) {
+		elements.messageLines.append(createLineRow(line));
+	}
+}
+
+function renderSectionComments() {
+	elements.sectionComments.replaceChildren();
+	if (messageData.sections.length === 0) {
+		const empty = document.createElement("p");
+		empty.className = "empty-hint";
+		empty.textContent = "This message does not have any non-empty sections to annotate.";
+		elements.sectionComments.append(empty);
+		return;
+	}
+	for (const section of messageData.sections) {
+		elements.sectionComments.append(createSectionCard(section));
+	}
+}
+
+function collectPayload() {
+	return {
+		type: "submit",
+		overallComment: state.overallComment,
+		inlineComments: Array.from(state.inlineComments.entries()).map(([line, body]) => ({ line, body })),
+		sectionComments: Array.from(state.sectionComments.entries()).map(([sectionId, body]) => ({ sectionId, body })),
+	};
+}
+
+function sendPayload(payload) {
+	window.glimpse?.send?.(payload);
+	window.glimpse?.close?.();
+}
+
+function submit() {
+	if (feedbackCount() === 0) {
+		setStatus("Add at least one comment before submitting.", "error");
+		return;
+	}
+	sendPayload(collectPayload());
+}
+
+function cancel() {
+	sendPayload({ type: "cancel" });
+}
+
+elements.overallComment.addEventListener("input", () => {
+	state.overallComment = elements.overallComment.value;
+	updateSubmitState();
+});
+
+elements.submitButton.addEventListener("click", submit);
+
+elements.cancelButton.addEventListener("click", cancel);
+
+document.addEventListener("keydown", (event) => {
+	if ((event.metaKey || event.ctrlKey) && event.key === "Enter") {
+		event.preventDefault();
+		submit();
+		return;
+	}
+	if (event.key === "Escape") {
+		event.preventDefault();
+		cancel();
+	}
+});
+
+renderMessageLines();
+renderSectionComments();
+updateSubmitState();

package/web/index.html

@@ -0,0 +1,322 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>annotate last message</title>
+<style>
+  :root {
+    color-scheme: dark;
+    --bg: #0d1117;
+    --panel: #151b23;
+    --panel-hover: #1f242c;
+    --border: #30363d;
+    --text: #f0f6fc;
+    --muted: #9198a1;
+    --accent: #4493f8;
+    --accent-strong: #1f6feb;
+    --success: #238636;
+    --success-strong: #2ea043;
+    --danger: #da3633;
+  }
+
+  * { box-sizing: border-box; }
+  html, body {
+    margin: 0;
+    width: 100%;
+    height: 100%;
+    background: var(--bg);
+    color: var(--text);
+    font: 14px/1.5 Inter, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  }
+
+  body {
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+  }
+
+  button, textarea {
+    font: inherit;
+  }
+
+  button {
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    background: var(--panel);
+    color: var(--text);
+    cursor: pointer;
+  }
+
+  button:hover:not(:disabled) {
+    background: var(--panel-hover);
+  }
+
+  button:disabled {
+    opacity: 0.45;
+    cursor: default;
+  }
+
+  textarea {
+    width: 100%;
+    min-height: 104px;
+    padding: 10px 12px;
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    resize: vertical;
+    background: #0b1118;
+    color: var(--text);
+  }
+
+  textarea:focus {
+    outline: 2px solid rgba(68, 147, 248, 0.35);
+    border-color: var(--accent);
+  }
+
+  .page-header,
+  .page-footer {
+    padding: 16px 20px;
+    border-bottom: 1px solid var(--border);
+    background: rgba(13, 17, 23, 0.96);
+  }
+
+  .page-footer {
+    border-top: 1px solid var(--border);
+    border-bottom: none;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
+  }
+
+  .page-header h1 {
+    margin: 0 0 6px;
+    font-size: 18px;
+  }
+
+  .page-header p,
+  .status,
+  .empty-hint,
+  .line-meta,
+  .section-meta {
+    margin: 0;
+    color: var(--muted);
+  }
+
+  .layout {
+    flex: 1;
+    min-height: 0;
+    display: grid;
+    grid-template-columns: minmax(0, 1.7fr) minmax(340px, 0.95fr);
+    gap: 20px;
+    padding: 20px;
+    overflow: hidden;
+  }
+
+  .panel {
+    min-height: 0;
+    border: 1px solid var(--border);
+    border-radius: 14px;
+    background: var(--panel);
+    overflow: hidden;
+  }
+
+  .panel-header {
+    padding: 14px 16px;
+    border-bottom: 1px solid var(--border);
+  }
+
+  .panel-header h2,
+  .sidebar-stack h2,
+  .sidebar-stack h3 {
+    margin: 0 0 4px;
+    font-size: 14px;
+  }
+
+  .message-lines {
+    height: 100%;
+    overflow: auto;
+    padding: 8px 0 16px;
+  }
+
+  .message-line {
+    padding: 10px 16px 0;
+  }
+
+  .message-line-row {
+    display: grid;
+    grid-template-columns: 52px minmax(0, 1fr) auto;
+    gap: 12px;
+    align-items: start;
+  }
+
+  .line-number {
+    color: var(--muted);
+    font: 12px/1.6 ui-monospace, SFMono-Regular, Menlo, monospace;
+    text-align: right;
+    padding-top: 2px;
+  }
+
+  .line-text {
+    margin: 0;
+    white-space: pre-wrap;
+    word-break: break-word;
+    font: 13px/1.6 ui-monospace, SFMono-Regular, Menlo, monospace;
+  }
+
+  .inline-toggle {
+    min-width: 112px;
+    padding: 7px 10px;
+    font-size: 12px;
+  }
+
+  .inline-toggle[data-active="true"] {
+    border-color: rgba(68, 147, 248, 0.45);
+    background: rgba(68, 147, 248, 0.12);
+    color: #c2ddff;
+  }
+
+  .inline-editor {
+    margin: 10px 0 0 64px;
+    padding: 12px;
+    border: 1px solid var(--border);
+    border-radius: 10px;
+    background: rgba(1, 4, 9, 0.28);
+  }
+
+  .inline-editor[hidden] {
+    display: none;
+  }
+
+  .inline-editor textarea {
+    min-height: 88px;
+  }
+
+  .sidebar-stack {
+    height: 100%;
+    overflow: auto;
+    display: flex;
+    flex-direction: column;
+    gap: 16px;
+    padding-right: 4px;
+  }
+
+  .sidebar-panel {
+    border: 1px solid var(--border);
+    border-radius: 14px;
+    background: var(--panel);
+    padding: 16px;
+  }
+
+  .section-card {
+    padding: 12px;
+    border: 1px solid var(--border);
+    border-radius: 10px;
+    background: rgba(1, 4, 9, 0.18);
+  }
+
+  .section-card + .section-card {
+    margin-top: 12px;
+  }
+
+  .section-preview {
+    margin: 8px 0 10px;
+    padding: 10px 12px;
+    border-radius: 8px;
+    background: #0b1118;
+    font: 12px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace;
+    white-space: pre-wrap;
+    word-break: break-word;
+  }
+
+  .empty-hint {
+    padding: 12px 0 0;
+  }
+
+  .footer-actions {
+    display: flex;
+    gap: 10px;
+  }
+
+  .footer-actions button {
+    padding: 10px 14px;
+  }
+
+  .submit-button {
+    border-color: rgba(46, 160, 67, 0.5);
+    background: var(--success);
+  }
+
+  .submit-button:hover:not(:disabled) {
+    background: var(--success-strong);
+  }
+
+  .cancel-button:hover:not(:disabled) {
+    border-color: rgba(218, 54, 51, 0.45);
+  }
+
+  .status[data-state="error"] {
+    color: #ffb3b3;
+  }
+
+  .status[data-state="ready"] {
+    color: #7ee787;
+  }
+
+  @media (max-width: 1100px) {
+    .layout {
+      grid-template-columns: 1fr;
+      overflow: auto;
+    }
+
+    .panel,
+    .sidebar-stack {
+      min-height: 520px;
+    }
+  }
+</style>
+</head>
+<body>
+<header class="page-header">
+  <h1>Annotate last assistant message</h1>
+  <p>Review the latest assistant text, add inline or section notes, and submit a structured prompt back to the editor.</p>
+</header>
+
+<div class="layout">
+  <section class="panel">
+    <div class="panel-header">
+      <h2>Assistant text</h2>
+      <p class="line-meta">Click <strong>Add inline note</strong> beside any line to attach focused feedback.</p>
+    </div>
+    <div id="message-lines" class="message-lines"></div>
+  </section>
+
+  <aside class="sidebar-stack">
+    <section class="sidebar-panel">
+      <h2>Overall guidance</h2>
+      <p class="section-meta">Optional high-level direction for the next response or plan update.</p>
+      <textarea id="overall-comment" placeholder="Explain what should change overall, what to clarify, or what plan adjustments you want."></textarea>
+    </section>
+
+    <section class="sidebar-panel">
+      <h2>Section comments</h2>
+      <p class="section-meta">Add broader notes for a paragraph or block from the assistant message.</p>
+      <div id="section-comments"></div>
+    </section>
+  </aside>
+</div>
+
+<footer class="page-footer">
+  <p id="status" class="status">Add any feedback you want to send back to the editor.</p>
+  <div class="footer-actions">
+    <button id="cancel-button" class="cancel-button" type="button">Cancel</button>
+    <button id="submit-button" class="submit-button" type="button">Submit feedback</button>
+  </div>
+</footer>
+
+<script id="annotate-last-message-data" type="application/json">"__INLINE_DATA__"</script>
+<script>
+__INLINE_JS__
+</script>
+</body>
+</html>