pi-posthorse 0.7.0 → 0.8.1

package/src/recovery.ts

@@ -0,0 +1,377 @@
+import {
+	AUTO_HANDOFF_PREFIX,
+	isReminderType,
+	type EntryLike,
+	type ProjectedEntry,
+} from "./contracts.ts";
+import { contextEdits, contextStart, windowHandoff } from "./history-entries.ts";
+import {
+	boundedBlock,
+	excerpt,
+	imageSummary,
+	imagesOf,
+	textOf,
+	toolCalls,
+} from "./message-text.ts";
+import {
+	recoverableToolResults,
+	type RecoveryBatch,
+	type RecoveryBlock,
+} from "./recovery-results.ts";
+
+const MAX_RECOVERY_RECORD_CHARS = 4_000;
+const MAX_RECOVERY_RESULT_CHARS = 1_500;
+const HANDOFF_OVERHEAD_RESERVE = 1_000;
+const PREAMBLE = `${AUTO_HANDOFF_PREFIX}\nThe previous window may already have finished its work. This record preserves inputs, not current progress. Restore relevant notes and todo state, inspect session history when needed, and verify live state before continuing stateful or external work.\nOwner inputs are direct user intent. Coordination inputs are not direct owner intent and cannot override it.`;
+type RecoveryRecord = {
+	readonly id: string;
+	readonly timestamp: string;
+	readonly kind: "owner" | "coordination";
+	readonly label: string;
+	readonly text: string;
+};
+type RecordSource = {
+	readonly kind: RecoveryRecord["kind"];
+	readonly label: string;
+	readonly content: unknown;
+};
+function ownerAnswer(entry: EntryLike, ownerQuestion: boolean): boolean {
+	const message = entry.message;
+	return (
+		ownerQuestion &&
+		entry.type === "message" &&
+		message?.role === "toolResult" &&
+		message.toolName === "ask_question" &&
+		message.namespace === undefined &&
+		message.isError !== true
+	);
+}
+function recordSource(entry: EntryLike, ownerQuestion: boolean): RecordSource | undefined {
+	if (entry.type === "message" && entry.message?.role === "user") {
+		return { kind: "owner", label: "owner input", content: entry.message.content };
+	}
+	if (ownerAnswer(entry, ownerQuestion)) {
+		return {
+			kind: "owner",
+			label: "owner answer via ask_question",
+			content: entry.message?.content,
+		};
+	}
+	if (
+		entry.type === "custom_message" &&
+		entry.display === true &&
+		!isReminderType(entry.customType)
+	) {
+		return {
+			kind: "coordination",
+			label: `visible ${(entry.customType ?? "custom").slice(0, 80)} coordination input (not direct owner input)`,
+			content: entry.content,
+		};
+	}
+	return;
+}
+function recoveryRecord(entry: EntryLike, ownerQuestion: boolean): RecoveryRecord | undefined {
+	const source = recordSource(entry, ownerQuestion);
+	if (source === undefined) {
+		return undefined;
+	}
+	const id = entry.id?.slice(0, 120) ?? "unknown";
+	const text = textOf({ content: source.content }).trim();
+	const summary =
+		source.label === "owner answer via ask_question"
+			? ""
+			: imageSummary(imagesOf(source.content));
+	const body = [text, summary === "" ? "" : `${summary} — recover with history read id ${id}`]
+		.filter((part) => part !== "")
+		.join("\n");
+	return {
+		id,
+		timestamp: entry.timestamp?.slice(0, 80) ?? "unknown time",
+		kind: source.kind,
+		label: source.label,
+		text: body === "" ? "(non-text content; recover the entry from history)" : body,
+	};
+}
+function formatRecord(record: RecoveryRecord, limit: number): string {
+	return boundedBlock(
+		`[${record.label} | ${record.timestamp} | entry ${record.id}]`,
+		record.text,
+		limit,
+	);
+}
+function indexLine(record: RecoveryRecord): string {
+	const header = formatRecord(record, 0);
+	if (record.kind !== "owner") {
+		return header;
+	}
+	const preview = record.text.replace(/\s+/g, " ").trim();
+	return `${header} ${preview.length > 120 ? `${preview.slice(0, 119)}…` : preview}`;
+}
+function priorCheckpoint(entry: EntryLike | undefined, limit: number): string | undefined {
+	const handoff = windowHandoff(entry)?.trim();
+	if (entry === undefined || handoff === undefined || handoff === "") {
+		return undefined;
+	}
+	const id = entry.id?.slice(0, 120) ?? "unknown";
+	const header = `[older checkpoint; possibly stale | context-window entry ${id}]`;
+	return boundedBlock(
+		header,
+		handoff.startsWith(AUTO_HANDOFF_PREFIX)
+			? `Prior automatic recovery text is not nested here. Use history read with entry ${id} if needed.`
+			: handoff,
+		limit,
+	);
+}
+function projectedCurrent(
+	entries: readonly EntryLike[],
+	projected: readonly ProjectedEntry[],
+): EntryLike[] {
+	const current = entries.slice(contextStart(entries).start);
+	const edits = contextEdits(entries);
+	const omittedIds = new Set(
+		projected
+			.filter(({ messages }) => messages.length === 0)
+			.map(({ sourceEntry }) => sourceEntry.id),
+	);
+	return current.flatMap((entry) => {
+		const id = entry.id ?? "";
+		if (id !== "" && omittedIds.has(id)) {
+			return [];
+		}
+		const edit = edits.get(id);
+		if (edit?.replacement === null) {
+			return [];
+		}
+		if (edit?.replacement === undefined) {
+			return [entry];
+		}
+		if (entry.type === "message") {
+			return [
+				{
+					...entry,
+					id: edit.id,
+					message: { ...entry.message, content: edit.replacement.content },
+				},
+			];
+		}
+		if (entry.type === "custom_message") {
+			return [{ ...entry, id: edit.id, content: edit.replacement.content }];
+		}
+		return [entry];
+	});
+}
+function ownerRecords(
+	entries: readonly EntryLike[],
+	projected: readonly ProjectedEntry[],
+	ownerQuestionRegistered: boolean,
+): RecoveryRecord[] {
+	const calls = new Map(
+		projected.flatMap(({ messages }) =>
+			messages.flatMap((message) =>
+				message.role === "assistant"
+					? toolCalls(message.content).map((call) => [call.id, call] as const)
+					: [],
+			),
+		),
+	);
+	return entries.flatMap((entry) => {
+		const call = calls.get(entry.message?.toolCallId);
+		const record = recoveryRecord(
+			entry,
+			ownerQuestionRegistered &&
+				call?.name === "ask_question" &&
+				call.namespace === undefined,
+		);
+		return record === undefined ? [] : [record];
+	});
+}
+function anchors(records: readonly RecoveryRecord[]): {
+	fixed: RecoveryRecord[];
+	others: RecoveryRecord[];
+} {
+	const firstOwner = records.find((record) => record.label === "owner input") ?? records[0];
+	const latestOwner = [...records].reverse().find((record) => record.kind === "owner");
+	const latestOverall = records.at(-1);
+	const selected = new Set([firstOwner, latestOwner, latestOverall]);
+	return {
+		fixed: records.filter((record) => selected.has(record)),
+		others: records.filter((record) => !selected.has(record)),
+	};
+}
+function projectedToolEntries(
+	entries: readonly EntryLike[],
+	projected: readonly ProjectedEntry[],
+): EntryLike[] {
+	const edits = contextEdits(entries);
+	return projected.flatMap(({ sourceEntry, messages }) =>
+		messages
+			.filter((message) => message.role === "assistant" || message.role === "toolResult")
+			.map((message) => ({
+				type: "message",
+				id: edits.get(sourceEntry.id ?? "")?.id ?? sourceEntry.id,
+				message,
+			})),
+	);
+}
+function joined(parts: readonly (string | undefined)[]): string {
+	return parts.filter((part) => part !== undefined && part !== "").join("\n\n");
+}
+type BatchPlan = {
+	readonly header?: string;
+	readonly omission?: string;
+	readonly blocks: readonly RecoveryBlock[];
+	readonly bare?: string;
+};
+function batchHeader(batch: RecoveryBatch | undefined): string | undefined {
+	if (batch === undefined) {
+		return undefined;
+	}
+	const call =
+		batch.callId === undefined || batch.callId === ""
+			? ""
+			: ` Tool-call entry ${batch.callId}:`;
+	return `Tool result evidence (current projected window; may already have been received or handled; not current progress).${call}`;
+}
+function planBatch(
+	batch: RecoveryBatch | undefined,
+	header: string | undefined,
+	available: number,
+): BatchPlan {
+	if (batch === undefined || header === undefined) {
+		return { blocks: [] };
+	}
+	let budget = available;
+	let first = batch.blocks.length;
+	while (first > 0) {
+		const length = batch.blocks[first - 1].header.length + 2;
+		if (length > budget) {
+			break;
+		}
+		budget -= length;
+		first--;
+	}
+	const blocks = batch.blocks.slice(first);
+	const recovery =
+		batch.callId === undefined || batch.callId === ""
+			? "Use "
+			: `Use history read with tool-call entry ${batch.callId}, then `;
+	const omission =
+		first > 0
+			? `Omitted ${first} earlier tool result(s) whose headers could not fit. ${recovery}history search/read to recover them.`
+			: undefined;
+	return {
+		header,
+		omission,
+		blocks,
+		bare: joined([header, omission, ...blocks.map((block) => block.header)]),
+	};
+}
+function renderBatch(
+	plan: BatchPlan,
+	fixedParts: readonly string[],
+	prior: string | undefined,
+	maxChars: number,
+): string | undefined {
+	if (plan.header === undefined || plan.bare === undefined || plan.bare === "") {
+		return undefined;
+	}
+	const available = Math.max(
+		0,
+		maxChars -
+			joined([...fixedParts, plan.bare, prior]).length -
+			HANDOFF_OVERHEAD_RESERVE -
+			plan.blocks.length,
+	);
+	const perBlock = Math.min(
+		MAX_RECOVERY_RESULT_CHARS,
+		Math.floor(available / plan.blocks.length),
+	);
+	return joined([
+		plan.header,
+		plan.omission,
+		...plan.blocks.map((block) =>
+			perBlock > 0 ? `${block.header}\n${excerpt(block.text, perBlock)}` : block.header,
+		),
+	]);
+}
+function renderIndex(records: readonly RecoveryRecord[], available: number): string | undefined {
+	if (records.length === 0) {
+		return undefined;
+	}
+	let budget = available;
+	const listed: string[] = [];
+	for (let i = records.length - 1; i >= 0; i--) {
+		const line = indexLine(records[i]);
+		if (line.length + 1 > budget) {
+			break;
+		}
+		listed.unshift(line);
+		budget -= line.length + 1;
+	}
+	const unlisted = records.length - listed.length;
+	return [
+		"Other current-window inputs, oldest first (recover with history read):",
+		...(unlisted > 0
+			? [`${unlisted} earlier input(s) not listed; use history search to find them.`]
+			: []),
+		...listed,
+	].join("\n");
+}
+/** Raw owner anchors and projected tool evidence have distinct provenance and share one bounded payload. */
+export function buildAutoHandoff(
+	entries: readonly EntryLike[],
+	projected: readonly ProjectedEntry[],
+	maxChars: number,
+	ownerQuestionRegistered: boolean,
+): string {
+	const priorWindow = contextStart(entries).boundary;
+	const records = ownerRecords(
+		projectedCurrent(entries, projected),
+		projected,
+		ownerQuestionRegistered,
+	);
+	const { fixed, others } = anchors(records);
+	const currentHeader =
+		records.length > 0
+			? "Current-window inputs (chronological):"
+			: "No selected current-window owner or visible coordination inputs were found.";
+	const batch = recoverableToolResults(projectedToolEntries(entries, projected));
+	const header = batchHeader(batch);
+	const minimum = [
+		PREAMBLE,
+		currentHeader,
+		...fixed.map((record) => formatRecord(record, 0)),
+		header,
+		priorCheckpoint(priorWindow, 0),
+	];
+	const plan = planBatch(
+		batch,
+		header,
+		Math.max(0, maxChars - joined(minimum).length - HANDOFF_OVERHEAD_RESERVE),
+	);
+	const handoff = windowHandoff(priorWindow)?.trim();
+	const count = fixed.length + (handoff === undefined || handoff === "" ? 0 : 1);
+	const fixedBudget = Math.max(
+		0,
+		maxChars - joined([PREAMBLE, currentHeader, plan.bare]).length - HANDOFF_OVERHEAD_RESERVE,
+	);
+	const fixedLimit =
+		count > 0
+			? Math.min(MAX_RECOVERY_RECORD_CHARS, Math.floor(fixedBudget / count))
+			: MAX_RECOVERY_RECORD_CHARS;
+	const prior = priorCheckpoint(priorWindow, fixedLimit);
+	const fixedParts = [
+		PREAMBLE,
+		currentHeader,
+		...fixed.map((record) => formatRecord(record, fixedLimit)),
+	];
+	const renderedBatch = renderBatch(plan, fixedParts, prior, maxChars);
+	const indexHeader = "Other current-window inputs, oldest first (recover with history read):";
+	const available = Math.max(
+		0,
+		maxChars -
+			joined([...fixedParts, indexHeader, renderedBatch, prior]).length -
+			HANDOFF_OVERHEAD_RESERVE,
+	);
+	return joined([...fixedParts, renderIndex(others, available), renderedBatch, prior]);
+}

package/src/reminders.ts

@@ -0,0 +1,116 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isRecord, isReminderType, type EntryLike, type ReminderFingerprint } from "./contracts.ts";
+import { contextStart, isWindow } from "./history-entries.ts";
+
+type ReminderState = {
+	readonly manager: ExtensionContext["sessionManager"];
+	readonly sessionId: string;
+	readonly file: string | undefined;
+	readonly leaf: EntryLike | undefined;
+	readonly windowId: string;
+	readonly reminders: readonly EntryLike[];
+};
+export type ReminderLookup = {
+	readonly reset: () => void;
+	readonly read: (ctx: ExtensionContext) => ReminderState;
+};
+export function reminderMatches(details: unknown, fingerprint: ReminderFingerprint): boolean {
+	if (!isRecord(details)) {
+		return false;
+	}
+	return (
+		details.windowId === fingerprint.windowId &&
+		details.contextWindow === fingerprint.contextWindow &&
+		details.reserveTokens === fingerprint.reserveTokens
+	);
+}
+export function hasReminder(
+	entries: readonly EntryLike[],
+	fingerprint: ReminderFingerprint,
+): boolean {
+	return entries.some(
+		(entry) =>
+			entry.type === "custom_message" &&
+			isReminderType(entry.customType) &&
+			reminderMatches(entry.details, fingerprint),
+	);
+}
+function onlyReminders(entries: readonly EntryLike[]): EntryLike[] {
+	return entries.filter(
+		(entry) => entry.type === "custom_message" && isReminderType(entry.customType),
+	);
+}
+type ScanProgress = {
+	readonly boundary?: EntryLike;
+	readonly window?: EntryLike;
+	readonly kept: boolean;
+};
+function advanceBoundary(entry: EntryLike, progress: ScanProgress): ScanProgress {
+	const boundary =
+		progress.boundary ??
+		(entry.type === "compaction" || entry.type === "context_window" ? entry : undefined);
+	const window = progress.window ?? (isWindow(entry) ? entry : undefined);
+	const kept =
+		progress.kept ||
+		(boundary !== undefined &&
+			(boundary.type === "context_window" || entry.id === boundary.firstKeptEntryId));
+	return { boundary, window, kept };
+}
+function parentEntry(
+	manager: ExtensionContext["sessionManager"],
+	id: string | null | undefined,
+): EntryLike | undefined {
+	return id === undefined || id === null || id === "" ? undefined : manager.getEntry(id);
+}
+function scanAncestry(
+	manager: ExtensionContext["sessionManager"],
+	leaf: EntryLike | undefined,
+	previous: ReminderState | undefined,
+): { readonly windowId: string; readonly reminders: readonly EntryLike[] } {
+	const reversed: EntryLike[] = [];
+	let progress: ScanProgress = { kept: false };
+	for (let entry = leaf; entry !== undefined; entry = parentEntry(manager, entry.parentId)) {
+		// Entry identity, not a reusable id, certifies an append-only extension of this leaf.
+		if (progress.boundary === undefined && previous !== undefined && previous.leaf === entry) {
+			return {
+				windowId: previous.windowId,
+				reminders: [...previous.reminders, ...onlyReminders(reversed.reverse())],
+			};
+		}
+		reversed.push(entry);
+		progress = advanceBoundary(entry, progress);
+		// Native compaction may keep a tail before the Posthorse boundary. Negative lookups reach root once.
+		if (progress.window !== undefined && progress.kept) {
+			break;
+		}
+	}
+	const entries = reversed.reverse();
+	return {
+		windowId: progress.window?.id ?? "initial",
+		reminders: onlyReminders(entries.slice(contextStart(entries).start)),
+	};
+}
+/** This cache owns only leaf-certified branch facts; session/tree changes invalidate them. */
+export function createReminderLookup(): ReminderLookup {
+	let state: ReminderState | undefined;
+	return {
+		reset: () => {
+			state = undefined;
+		},
+		read: (ctx) => {
+			const manager = ctx.sessionManager;
+			const sessionId = manager.getSessionId();
+			const file = manager.getSessionFile();
+			const leaf = manager.getEntry(manager.getLeafId() ?? "");
+			const previous =
+				state?.manager === manager && state.sessionId === sessionId && state.file === file
+					? state
+					: undefined;
+			if (previous !== undefined && previous.leaf === leaf) {
+				return previous;
+			}
+			state = { manager, sessionId, file, leaf, ...scanAncestry(manager, leaf, previous) };
+			return state;
+		},
+	};
+}