@wassname2/pi-annotated-journal 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oliver Maclaren
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# @wassname2/pi-annotated-journal
+
+Annotate recent Pi messages in `$VISUAL` or `$EDITOR`, and keep the feedback in a Markdown journal.
+
+```bash
+pi install npm:@wassname2/pi-annotated-journal
+```
+
+```text
+/annotate       # last 6 user/assistant messages
+/annotate 10    # last 10
+```
+
+Pi opens a Markdown transcript with every source line blockquoted. Write feedback as unquoted
+text near the line it refers to, then save and close. The extension then:
+
+1. appends the annotated transcript to `docs/human_journal.md`;
+2. records the entry in the Pi session;
+3. sends the transcript to the model as hidden context and starts the next turn.
+
+Nothing is saved or sent if you add no unquoted text. An editor error cancels the operation.
+Without `$VISUAL` or `$EDITOR`, Pi's built-in editor is used.
+
+Every interactive or RPC prompt is also appended as a quoted `User message` record. Extension-injected messages are excluded. The journal is not added to model context automatically; ask Pi to read it when it is useful.
+
+`PI_ANNOTATE_JOURNAL` sets the journal path. Relative paths resolve from Pi's working directory.
+
+<!-- PI -->
+
+## Export supervision data
+
+```bash
+pi-supervision-export --journal docs/human_journal.md --output supervision.jsonl
+```
+
+Reads the session files referenced by the journal. `--session PATH`, repeatable, restricts the
+export. Records are typed `user_message` or `human_annotation`; an annotation carries the message
+ID and the source line it follows.
+
+## Development
+
+```bash
+npm install
+npm run check
+```
+
+The external-editor flow is adapted from
+[pi-annotated-reply](https://github.com/omaclaren/pi-annotated-reply).

package/index.ts

@@ -0,0 +1,255 @@
+import { BorderedLoader } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { spawnSync } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import {
+	buildAnnotationTemplate,
+	buildJournalRecord,
+	buildPrompt,
+	buildUserMessageRecord,
+	extractAnnotations,
+	journalHeader,
+	type ConversationMessage,
+	type ConversationRole,
+	type JournalRecordMetadata,
+	type UserMessageRecordMetadata,
+} from "./src/core.ts";
+
+const DEFAULT_MESSAGE_COUNT = 6;
+const MAX_MESSAGE_COUNT = 100;
+const DEFAULT_JOURNAL_PATH = "docs/human_journal.md";
+
+type EditorResult =
+	| { ok: true; edited: string }
+	| { ok: false; cancelled: true }
+	| { ok: false; message: string };
+
+type ParsedEditor = { command: string; args: string[] };
+
+function parseCount(args: string): number | null {
+	const value = args.trim();
+	if (!value) return DEFAULT_MESSAGE_COUNT;
+	if (!/^\d+$/.test(value)) return null;
+	const count = Number(value);
+	return Number.isSafeInteger(count) && count >= 1 && count <= MAX_MESSAGE_COUNT ? count : null;
+}
+
+function textFromContent(content: unknown): string {
+	if (typeof content === "string") return content.trimEnd();
+	if (!Array.isArray(content)) return "";
+	return content
+		.map((part) => {
+			if (!part || typeof part !== "object" || !("type" in part)) return "";
+			if (part.type === "text" && "text" in part && typeof part.text === "string") return part.text;
+			if (part.type === "image") return "[image omitted from annotation view]";
+			return "";
+		})
+		.filter(Boolean)
+		.join("\n\n")
+		.trimEnd();
+}
+
+function conversationMessage(entry: SessionEntry): ConversationMessage | null {
+	if (entry.type !== "message") return null;
+	const message = entry.message;
+	if (message.role !== "user" && message.role !== "assistant") return null;
+	const text = textFromContent(message.content);
+	if (!text.trim()) return null;
+	return {
+		id: entry.id,
+		role: message.role as ConversationRole,
+		timestamp: entry.timestamp,
+		text,
+	};
+}
+
+function recentConversation(ctx: ExtensionCommandContext, count: number): ConversationMessage[] {
+	return ctx.sessionManager
+		.getBranch()
+		.map(conversationMessage)
+		.filter((message): message is ConversationMessage => message !== null)
+		.slice(-count);
+}
+
+function parseEditorCommand(spec: string): ParsedEditor | null {
+	const tokens = spec.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g);
+	if (!tokens?.length) return null;
+	const unquote = (token: string) => {
+		if (token.length >= 2 && ((token.startsWith('"') && token.endsWith('"')) || (token.startsWith("'") && token.endsWith("'")))) {
+			return token.slice(1, -1);
+		}
+		return token;
+	};
+	const command = unquote(tokens[0] ?? "").trim();
+	if (!command) return null;
+	return { command, args: tokens.slice(1).map(unquote) };
+}
+
+async function editExternally(ctx: ExtensionCommandContext, prefill: string, commandSpec: string): Promise<EditorResult> {
+	const editor = parseEditorCommand(commandSpec);
+	if (!editor) return { ok: false, message: `Could not parse $VISUAL/$EDITOR: ${commandSpec}` };
+
+	const result = await ctx.ui.custom<EditorResult>((tui, theme, _keybindings, done) => {
+		const loader = new BorderedLoader(tui, theme, `Opening ${editor.command}...`);
+		let settled = false;
+		const finish = (value: EditorResult) => {
+			if (settled) return;
+			settled = true;
+			done(value);
+		};
+		loader.onAbort = () => finish({ ok: false, cancelled: true });
+
+		void Promise.resolve().then(() => {
+			const tempDirectory = mkdtempSync(join(tmpdir(), "pi-annotate-"));
+			const tempFile = join(tempDirectory, "annotation.md");
+			let tuiStopped = false;
+			try {
+				writeFileSync(tempFile, prefill, { encoding: "utf8", mode: 0o600 });
+				if (settled) return;
+				tui.stop();
+				tuiStopped = true;
+				const run = spawnSync(editor.command, [...editor.args, tempFile], { stdio: "inherit" });
+				if (run.error) return finish({ ok: false, message: run.error.message });
+				if (run.status !== 0) return finish({ ok: false, cancelled: true });
+				finish({ ok: true, edited: readFileSync(tempFile, "utf8") });
+			} catch (error) {
+				finish({ ok: false, message: error instanceof Error ? error.message : String(error) });
+			} finally {
+				rmSync(tempDirectory, { recursive: true, force: true });
+				if (tuiStopped) {
+					tui.start();
+					tui.requestRender(true);
+				}
+			}
+		});
+
+		return loader;
+	});
+	return result ?? { ok: false, cancelled: true };
+}
+
+async function editAnnotation(ctx: ExtensionCommandContext, prefill: string): Promise<EditorResult> {
+	const commandSpec = process.env.VISUAL?.trim() || process.env.EDITOR?.trim();
+	if (ctx.mode === "tui" && commandSpec) return editExternally(ctx, prefill, commandSpec);
+	if (!ctx.hasUI) return { ok: false, message: "/annotate requires interactive Pi mode." };
+	if (!commandSpec) ctx.ui.notify("No $VISUAL/$EDITOR set; using Pi's built-in editor.", "warning");
+	const edited = await ctx.ui.editor("Annotate recent conversation", prefill);
+	return edited === undefined ? { ok: false, cancelled: true } : { ok: true, edited };
+}
+
+function journalPath(ctx: { cwd: string }): string {
+	const configured = process.env.PI_ANNOTATE_JOURNAL?.trim() || DEFAULT_JOURNAL_PATH;
+	return isAbsolute(configured) ? configured : resolve(ctx.cwd, configured);
+}
+
+function appendJournal(path: string, record: string): void {
+	mkdirSync(dirname(path), { recursive: true });
+	if (!existsSync(path)) {
+		writeFileSync(path, journalHeader(), { encoding: "utf8", mode: 0o600 });
+	}
+	const existing = readFileSync(path, "utf8");
+	const separator = existing.length === 0 || existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+	appendFileSync(path, `${separator}${record}`, "utf8");
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.on("input", (event, ctx) => {
+		if (event.source === "extension") return { action: "continue" };
+		const metadata: UserMessageRecordMetadata = {
+			schema: 1,
+			createdAt: new Date().toISOString(),
+			sessionId: ctx.sessionManager.getSessionId(),
+			sessionFile: ctx.sessionManager.getSessionFile() ?? null,
+			cwd: ctx.cwd,
+			source: event.source,
+		};
+		appendJournal(journalPath(ctx), buildUserMessageRecord(metadata, event.text));
+		return { action: "continue" };
+	});
+
+	pi.registerCommand("annotate", {
+		description: "Annotate the last N user/assistant messages in $EDITOR (default: 6), journal the feedback, and send it",
+		handler: async (args, ctx) => {
+			const count = parseCount(args);
+			if (count === null) {
+				ctx.ui.notify(`Usage: /annotate [N], where N is 1-${MAX_MESSAGE_COUNT}.`, "warning");
+				return;
+			}
+
+			await ctx.waitForIdle();
+			const messages = recentConversation(ctx, count);
+			if (messages.length === 0) {
+				ctx.ui.notify("No user or assistant text found in the current branch.", "warning");
+				return;
+			}
+
+			const edited = await editAnnotation(ctx, buildAnnotationTemplate(messages));
+			if (!edited.ok) {
+				if ("cancelled" in edited) ctx.ui.notify("Annotation cancelled.", "info");
+				else ctx.ui.notify(edited.message, "error");
+				return;
+			}
+
+			let annotations;
+			try {
+				annotations = extractAnnotations(edited.edited, messages.map((message) => message.id));
+			} catch (error) {
+				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+				return;
+			}
+			if (annotations.length === 0) {
+				ctx.ui.notify("No unquoted annotations found; nothing was sent or journaled.", "info");
+				return;
+			}
+
+			const createdAt = new Date().toISOString();
+			const path = journalPath(ctx);
+			const metadata: JournalRecordMetadata = {
+				schema: 1,
+				recordId: randomUUID(),
+				createdAt,
+				sessionId: ctx.sessionManager.getSessionId(),
+				sessionFile: ctx.sessionManager.getSessionFile() ?? null,
+				cwd: ctx.cwd,
+				messageIds: messages.map((message) => message.id),
+			};
+
+			try {
+				appendJournal(path, buildJournalRecord(metadata, edited.edited));
+			} catch (error) {
+				ctx.ui.notify(`Could not write ${path}: ${error instanceof Error ? error.message : String(error)}`, "error");
+				return;
+			}
+
+			pi.appendEntry("pi-annotate-journal", {
+				recordId: metadata.recordId,
+				journalPath: path,
+				messageIds: metadata.messageIds,
+				annotationCount: annotations.length,
+			});
+
+			const prompt = buildPrompt(edited.edited);
+			try {
+				pi.sendMessage(
+					{
+						customType: "pi-annotated-journal",
+						content: prompt,
+						display: false,
+						details: { recordId: metadata.recordId },
+					},
+					{ triggerTurn: true },
+				);
+				ctx.ui.notify(`Saved ${annotations.length} annotation${annotations.length === 1 ? "" : "s"} to ${path}.`, "info");
+			} catch (error) {
+				ctx.ui.setEditorText(prompt);
+				ctx.ui.notify(
+					`Journal saved, but automatic submission failed. The prompt is loaded in Pi's editor: ${error instanceof Error ? error.message : String(error)}`,
+					"error",
+				);
+			}
+		},
+	});
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@wassname2/pi-annotated-journal",
+  "version": "0.1.0",
+  "description": "Annotate recent Pi conversation turns and keep the feedback in a Markdown journal",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "annotation",
+    "human-in-the-loop",
+    "supervision"
+  ],
+  "bin": {
+    "pi-supervision-export": "./scripts/export-supervision.mjs"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "@types/node": "^24.3.0",
+    "typescript": "^5.7.3"
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --test tests/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wassname/pi-annotated-journal.git"
+  },
+  "homepage": "https://github.com/wassname/pi-annotated-journal#readme",
+  "bugs": {
+    "url": "https://github.com/wassname/pi-annotated-journal/issues"
+  }
+}

package/scripts/export-supervision.mjs

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const BODY_START = "<!-- pi-annotate-body -->";
+const BODY_END = "<!-- /pi-annotate-body -->";
+const RECORD_END = "<!-- /pi-annotate-record -->";
+const MESSAGE_PREFIX = "<!-- pi-annotate-message:";
+
+function usage(exitCode = 0) {
+	const stream = exitCode === 0 ? process.stdout : process.stderr;
+	stream.write(`Usage: pi-supervision-export [options]\n\nOptions:\n  --journal PATH   Journal path (default: docs/human_journal.md)\n  --session PATH   Pi session JSONL; repeat for more than one\n  --output PATH    Write JSONL here instead of stdout\n  --help           Show this help\n\nWithout --session, session files referenced by journal records are read automatically.\n`);
+	process.exit(exitCode);
+}
+
+function parseArgs(argv) {
+	const options = { journal: "docs/human_journal.md", sessions: [], output: null };
+	for (let i = 0; i < argv.length; i += 1) {
+		const arg = argv[i];
+		if (arg === "--help" || arg === "-h") usage();
+		if (arg === "--journal" || arg === "--session" || arg === "--output") {
+			const value = argv[++i];
+			if (!value) usage(2);
+			if (arg === "--journal") options.journal = value;
+			if (arg === "--session") options.sessions.push(value);
+			if (arg === "--output") options.output = value;
+			continue;
+		}
+		process.stderr.write(`Unknown argument: ${arg}\n`);
+		usage(2);
+	}
+	return options;
+}
+
+function decode(encoded) {
+	return JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+}
+
+function annotationBody(record) {
+	const lines = record.replace(/\r\n/g, "\n").split("\n");
+	const start = lines.indexOf(BODY_START);
+	const end = lines.indexOf(BODY_END, start + 1);
+	if (start < 0 || end < 0 || end <= start) throw new Error("Malformed annotation body");
+	return lines.slice(start + 1, end).join("\n");
+}
+
+function parseLegacyAnnotations(body) {
+	const annotations = [];
+	let messageId = null;
+	let role = null;
+	let sourceLine = 0;
+	let pending = [];
+	let pendingAfterLine = 0;
+	const flush = () => {
+		const text = pending.join("\n").trim();
+		if (text) annotations.push({ messageId, role, afterSourceLine: pendingAfterLine, text });
+		pending = [];
+	};
+	for (const line of body.split("\n")) {
+		if (line.startsWith(MESSAGE_PREFIX) && line.endsWith(" -->")) {
+			flush();
+			const marker = decode(line.slice(MESSAGE_PREFIX.length, -4));
+			messageId = marker.id;
+			role = marker.role;
+			sourceLine = 0;
+			continue;
+		}
+		if (line === "## User" || line === "## Assistant" || /^<!--.*-->$/.test(line.trim())) continue;
+		if (line.startsWith(">")) {
+			flush();
+			sourceLine += 1;
+			continue;
+		}
+		if (line.trim() === "") {
+			flush();
+			continue;
+		}
+		if (pending.length === 0) pendingAfterLine = sourceLine;
+		pending.push(line);
+	}
+	flush();
+	return annotations;
+}
+
+function parseCurrentAnnotations(body, messageIds) {
+	const annotations = [];
+	let sectionIndex = 0;
+	let role = null;
+	let sourceLine = 0;
+	let pending = [];
+	let pendingAfterLine = 0;
+	const flush = () => {
+		const text = pending.join("\n").trim();
+		if (text) annotations.push({
+			messageId: messageIds[sectionIndex] ?? null,
+			role,
+			afterSourceLine: pendingAfterLine,
+			text,
+		});
+		pending = [];
+	};
+	for (const line of body.split("\n")) {
+		if (line === "# Annotate") continue;
+		if (line === "---") {
+			flush();
+			sectionIndex += 1;
+			role = null;
+			sourceLine = 0;
+			continue;
+		}
+		if (line.startsWith(">")) {
+			flush();
+			if (sourceLine === 0) {
+				const match = line.match(/^> (User|Assistant):(?: |$)/);
+				role = match?.[1] === "User" ? "user" : match?.[1] === "Assistant" ? "assistant" : null;
+			}
+			sourceLine += 1;
+			continue;
+		}
+		if (line.trim() === "") {
+			flush();
+			continue;
+		}
+		if (pending.length === 0) pendingAfterLine = sourceLine;
+		pending.push(line);
+	}
+	flush();
+	return annotations;
+}
+
+function parseAnnotations(record, messageIds) {
+	const body = annotationBody(record);
+	return body.includes("<!-- pi-annotate-template:v1 -->")
+		? parseLegacyAnnotations(body)
+		: parseCurrentAnnotations(body, messageIds);
+}
+
+function parseJournal(path) {
+	const lines = readFileSync(path, "utf8").replace(/\r\n/g, "\n").split("\n");
+	const records = [];
+	for (let index = 0; index < lines.length; index += 1) {
+		const match = lines[index]?.match(/^<!-- pi-annotate-record:([A-Za-z0-9_-]+) -->$/);
+		if (!match) continue;
+		const end = lines.indexOf(RECORD_END, index + 1);
+		if (end < 0) throw new Error(`Unterminated journal record at line ${index + 1}`);
+		const metadata = decode(match[1]);
+		const template = lines.slice(index + 1, end).join("\n").trim();
+		records.push({ metadata, annotations: parseAnnotations(template, metadata.messageIds ?? []) });
+		index = end;
+	}
+	return records;
+}
+
+function contentText(content) {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.filter((part) => part && part.type === "text" && typeof part.text === "string")
+		.map((part) => part.text)
+		.join("\n\n");
+}
+
+function readSession(path) {
+	const lines = readFileSync(path, "utf8").split(/\r?\n/).filter(Boolean);
+	let sessionId = null;
+	const records = [];
+	for (let index = 0; index < lines.length; index += 1) {
+		let entry;
+		try {
+			entry = JSON.parse(lines[index]);
+		} catch (error) {
+			throw new Error(`${path}:${index + 1}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		if (entry.type === "session") sessionId = entry.id;
+		if (entry.type !== "message" || entry.message?.role !== "user") continue;
+		const text = contentText(entry.message.content);
+		if (text.includes("<!-- pi-annotate-template:v1 -->")) continue;
+		records.push({
+			type: "user_message",
+			timestamp: entry.timestamp ?? new Date(entry.message.timestamp).toISOString(),
+			sessionId,
+			sessionFile: path,
+			entryId: entry.id,
+			parentId: entry.parentId ?? null,
+			text,
+		});
+	}
+	return { sessionId, records };
+}
+
+function main() {
+	const options = parseArgs(process.argv.slice(2));
+	const journalPath = resolve(options.journal);
+	const journalRecords = parseJournal(journalPath);
+	const explicitSessions = options.sessions.map((path) => resolve(path));
+	const sessionPaths = explicitSessions.length > 0
+		? explicitSessions
+		: [...new Set(journalRecords.map((record) => record.metadata.sessionFile).filter(Boolean))];
+
+	const output = [];
+	const selectedSessionIds = new Set();
+	for (const path of sessionPaths) {
+		try {
+			const session = readSession(path);
+			if (session.sessionId) selectedSessionIds.add(session.sessionId);
+			output.push(...session.records);
+		} catch (error) {
+			process.stderr.write(`warning: ${error instanceof Error ? error.message : String(error)}\n`);
+		}
+	}
+
+	for (const record of journalRecords) {
+		if (explicitSessions.length > 0 && !selectedSessionIds.has(record.metadata.sessionId)) continue;
+		record.annotations.forEach((annotation, ordinal) => {
+			output.push({
+				type: "human_annotation",
+				timestamp: record.metadata.createdAt,
+				sessionId: record.metadata.sessionId,
+				sessionFile: record.metadata.sessionFile,
+				recordId: record.metadata.recordId,
+				ordinal,
+				messageId: annotation.messageId,
+				role: annotation.role,
+				afterSourceLine: annotation.afterSourceLine,
+				text: annotation.text,
+			});
+		});
+	}
+
+	output.sort((a, b) => String(a.timestamp).localeCompare(String(b.timestamp)) || (a.ordinal ?? -1) - (b.ordinal ?? -1));
+	const jsonl = output.map((record) => JSON.stringify(record)).join("\n") + (output.length > 0 ? "\n" : "");
+	if (options.output) writeFileSync(resolve(options.output), jsonl, "utf8");
+	else process.stdout.write(jsonl);
+}
+
+try {
+	main();
+} catch (error) {
+	process.stderr.write(`pi-supervision-export: ${error instanceof Error ? error.message : String(error)}\n`);
+	process.exitCode = 1;
+}

package/src/core.ts

@@ -0,0 +1,250 @@
+export const TEMPLATE_VERSION = 2;
+
+export type ConversationRole = "user" | "assistant";
+
+export type ConversationMessage = {
+	id: string;
+	role: ConversationRole;
+	timestamp: string;
+	text: string;
+};
+
+export type Annotation = {
+	messageId: string | null;
+	role: ConversationRole | null;
+	afterSourceLine: number;
+	text: string;
+};
+
+export type JournalRecordMetadata = {
+	schema: 1;
+	recordId: string;
+	createdAt: string;
+	sessionId: string;
+	sessionFile: string | null;
+	cwd: string;
+	messageIds: string[];
+};
+
+export type UserMessageRecordMetadata = {
+	schema: 1;
+	createdAt: string;
+	sessionId: string;
+	sessionFile: string | null;
+	cwd: string;
+	source: "interactive" | "rpc";
+};
+
+const TEMPLATE_HEADING = "# Annotate";
+const SEPARATOR = "---";
+const BODY_START = "<!-- pi-annotate-body -->";
+const BODY_END = "<!-- /pi-annotate-body -->";
+const RECORD_PREFIX = "<!-- pi-annotate-record:";
+const RECORD_END = "<!-- /pi-annotate-record -->";
+const USER_MESSAGE_PREFIX = "<!-- pi-user-message:";
+const USER_MESSAGE_END = "<!-- /pi-user-message -->";
+const LEGACY_MESSAGE_PREFIX = "<!-- pi-annotate-message:";
+
+function encodeMetadata(value: unknown): string {
+	return Buffer.from(JSON.stringify(value), "utf8").toString("base64url");
+}
+
+function decodeMetadata<T>(encoded: string): T {
+	return JSON.parse(Buffer.from(encoded, "base64url").toString("utf8")) as T;
+}
+
+export function quoteMarkdown(text: string): string {
+	return text
+		.replace(/\r\n/g, "\n")
+		.split("\n")
+		.map((line) => (line.length > 0 ? `> ${line}` : ">"))
+		.join("\n");
+}
+
+function quoteMessage(message: ConversationMessage): string {
+	const role = message.role === "user" ? "User" : "Assistant";
+	const [first = "", ...rest] = message.text.replace(/\r\n/g, "\n").split("\n");
+	const lines = [`> ${role}: ${first}`, ...rest.map((line) => (line.length > 0 ? `> ${line}` : ">"))];
+	return lines.join("\n");
+}
+
+export function buildAnnotationTemplate(messages: ConversationMessage[]): string {
+	return [TEMPLATE_HEADING, "", messages.map(quoteMessage).join(`\n\n${SEPARATOR}\n\n`), ""].join("\n");
+}
+
+function flushAnnotation(
+	annotations: Annotation[],
+	pending: string[],
+	messageId: string | null,
+	role: ConversationRole | null,
+	afterSourceLine: number,
+): void {
+	const text = pending.join("\n").trim();
+	if (text) annotations.push({ messageId, role, afterSourceLine, text });
+	pending.length = 0;
+}
+
+function extractCurrentAnnotations(markdown: string, messageIds: readonly string[]): Annotation[] {
+	const annotations: Annotation[] = [];
+	const lines = markdown.replace(/\r\n/g, "\n").split("\n");
+	let sectionIndex = 0;
+	let sectionCount = 0;
+	let role: ConversationRole | null = null;
+	let sourceLine = 0;
+	let pending: string[] = [];
+	let pendingAfterLine = 0;
+
+	const flush = () => flushAnnotation(
+		annotations,
+		pending,
+		messageIds[sectionIndex] ?? null,
+		role,
+		pendingAfterLine,
+	);
+
+	for (const line of lines) {
+		if (line === TEMPLATE_HEADING && sectionCount === 0 && sourceLine === 0) continue;
+		if (line === SEPARATOR) {
+			flush();
+			sectionIndex += 1;
+			role = null;
+			sourceLine = 0;
+			continue;
+		}
+		if (line.startsWith(">")) {
+			flush();
+			if (sourceLine === 0) {
+				const match = line.match(/^> (User|Assistant):(?: |$)/);
+				if (!match) throw new Error("A message heading was changed. Re-run /annotate and keep the quoted User/Assistant prefixes.");
+				role = match[1] === "User" ? "user" : "assistant";
+				sectionCount += 1;
+			}
+			sourceLine += 1;
+			continue;
+		}
+		if (line.trim() === "") {
+			flush();
+			continue;
+		}
+		if (pending.length === 0) pendingAfterLine = sourceLine;
+		pending.push(line);
+	}
+	flush();
+
+	if (messageIds.length > 0 && sectionCount !== messageIds.length) {
+		throw new Error("Message separators were changed. Re-run /annotate and keep the quoted messages and --- separators.");
+	}
+	return annotations;
+}
+
+function bodyFromJournalRecord(markdown: string): string {
+	const lines = markdown.replace(/\r\n/g, "\n").split("\n");
+	const start = lines.indexOf(BODY_START);
+	const end = lines.indexOf(BODY_END, start + 1);
+	if (start < 0 || end < 0 || end <= start) throw new Error("Journal record has invalid body markers.");
+	return lines.slice(start + 1, end).join("\n");
+}
+
+function extractLegacyAnnotations(markdown: string): Annotation[] {
+	const body = bodyFromJournalRecord(markdown);
+	const annotations: Annotation[] = [];
+	let messageId: string | null = null;
+	let role: ConversationRole | null = null;
+	let sourceLine = 0;
+	let pending: string[] = [];
+	let pendingAfterLine = 0;
+	const flush = () => flushAnnotation(annotations, pending, messageId, role, pendingAfterLine);
+
+	for (const line of body.split("\n")) {
+		if (line.startsWith(LEGACY_MESSAGE_PREFIX) && line.endsWith(" -->")) {
+			flush();
+			const metadata = decodeMetadata<{ id: string; role: ConversationRole }>(line.slice(LEGACY_MESSAGE_PREFIX.length, -4));
+			messageId = metadata.id;
+			role = metadata.role;
+			sourceLine = 0;
+			continue;
+		}
+		if (line === "## User" || line === "## Assistant" || /^<!--.*-->$/.test(line.trim())) continue;
+		if (line.startsWith(">")) {
+			flush();
+			sourceLine += 1;
+			continue;
+		}
+		if (line.trim() === "") {
+			flush();
+			continue;
+		}
+		if (pending.length === 0) pendingAfterLine = sourceLine;
+		pending.push(line);
+	}
+	flush();
+	return annotations;
+}
+
+export function extractAnnotations(markdown: string, messageIds: readonly string[] = []): Annotation[] {
+	return extractCurrentAnnotations(markdown, messageIds);
+}
+
+export function buildPrompt(editedTemplate: string): string {
+	return editedTemplate.replace(/\r\n/g, "\n").trim();
+}
+
+export function buildJournalRecord(metadata: JournalRecordMetadata, editedTemplate: string): string {
+	const encoded = encodeMetadata(metadata);
+	return [
+		`## ${metadata.createdAt} · session ${metadata.sessionId}`,
+		"",
+		`${RECORD_PREFIX}${encoded} -->`,
+		BODY_START,
+		editedTemplate.replace(/\r\n/g, "\n").trim(),
+		BODY_END,
+		RECORD_END,
+		"",
+	].join("\n");
+}
+
+export function buildUserMessageRecord(metadata: UserMessageRecordMetadata, text: string): string {
+	return [
+		`## ${metadata.createdAt} · User message`,
+		"",
+		`${USER_MESSAGE_PREFIX}${encodeMetadata(metadata)} -->`,
+		quoteMarkdown(text),
+		USER_MESSAGE_END,
+		"",
+	].join("\n");
+}
+
+export function journalHeader(): string {
+	return [
+		"# Human supervision journal",
+		"",
+		"Quoted `User message` records are exact submitted prompts. `/annotate` records contain quoted prior conversation and unquoted feedback.",
+		"",
+	].join("\n");
+}
+
+export type ParsedJournalRecord = {
+	metadata: JournalRecordMetadata;
+	template: string;
+	annotations: Annotation[];
+};
+
+export function parseJournalRecords(markdown: string): ParsedJournalRecord[] {
+	const records: ParsedJournalRecord[] = [];
+	const lines = markdown.replace(/\r\n/g, "\n").split("\n");
+	for (let index = 0; index < lines.length; index += 1) {
+		const match = lines[index]?.match(/^<!-- pi-annotate-record:([A-Za-z0-9_-]+) -->$/);
+		if (!match) continue;
+		const end = lines.indexOf(RECORD_END, index + 1);
+		if (end < 0) throw new Error("Journal contains an unterminated pi-annotate record.");
+		const metadata = decodeMetadata<JournalRecordMetadata>(match[1] ?? "");
+		const recordBody = lines.slice(index + 1, end).join("\n").trim();
+		const template = bodyFromJournalRecord(recordBody);
+		const annotations = template.includes("<!-- pi-annotate-template:v1 -->")
+			? extractLegacyAnnotations(recordBody)
+			: extractCurrentAnnotations(template, metadata.messageIds);
+		records.push({ metadata, template, annotations });
+		index = end;
+	}
+	return records;
+}