pi-posthorse 0.10.21 → 0.10.22

package/README.md

@@ -1,6 +1,6 @@
 # Posthorse
 
-Posthorse starts fresh context windows for long [Pi](https://github.com/earendil-works/pi) tasks without an automatic model-generated summary. Stock Pi already preserves the session journal and retains a recent tail during compaction; Posthorse adds explicit notes and history retrieval, with a handoff or bounded recovery record instead of the automatic summary.
+Posthorse starts fresh context windows for long [Pi](https://github.com/earendil-works/pi) tasks without an automatic model-generated summary of the work. Stock Pi already preserves the session journal and retains a recent tail during compaction; Posthorse adds explicit notes and history retrieval, with a handoff or bounded recovery record instead of the automatic summary.
 
 ![A Pi conversation rolls into a fresh context window. Task notes and the complete session transcript remain available.](https://raw.githubusercontent.com/fitchmultz/pi-posthorse/main/.github/readme/context-rollover.png)
 
@@ -25,7 +25,7 @@ Give Pi your task. For example:
 
 Posthorse can send a routine task-note reminder before rollover. The reminder tells the model to save current task state if needed, then immediately continue the prescribed work. The context window is not a task deadline. The reminder does not require `new_context` or wake an agent after its final answer. Large turns can reach rollover before the reminder. See [Reminder timing](docs/reminder-timing.md) for the trigger and its relationship to Pi's reserve and retention settings.
 
-Automatic rollover retains a safe recent-message tail using Pi's `compaction.keepRecentTokens`, alongside a bounded recovery record for discarded inputs and tool evidence. It never calls a summarization model. The model must restore notes and check live state before it continues. Optional `new_context` deliberately retains no prior messages; manual `/compact` uses Pi's normal summarization.
+Automatic rollover retains a safe recent-message tail using Pi's `compaction.keepRecentTokens`, alongside a bounded recovery record for discarded inputs and tool evidence. No model summarizes the work. The model must restore notes and check live state before it continues. On [fitchmultz/pi](https://github.com/fitchmultz/pi), a Claude model also writes one line that points to the task note, so that Claude keeps [the reasoning of the retained replies](https://github.com/fitchmultz/pi-posthorse/blob/main/docs/context-recovery.md#claude-reasoning-in-the-retained-tail). Optional `new_context` deliberately retains no prior messages; manual `/compact` uses Pi's normal summarization.
 
 Posthorse does not schedule rollover when a provider cache expires. An idle session below the
 rollover threshold keeps its context; use an explicit `new_context` when a deliberate clean reset

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-posthorse",
-	"version": "0.10.21",
+	"version": "0.10.22",
 	"type": "module",
 	"description": "Posthorse: fresh context, same journey. No-summary context rollover for Pi, with sparse budget reminders, handoffs, notes, and history.",
 	"keywords": [

package/src/provider-summary.ts

@@ -0,0 +1,53 @@
+import * as host from "@earendil-works/pi-ai";
+
+/**
+ * A one-line summary block written by the provider at an automatic rollover.
+ *
+ * A host that implements `providerSummary` on a compaction asks the session's model for the block
+ * and sends it ahead of the retained tail, which keeps the reasoning of the tail's replies valid.
+ * The block carries no task state; the recovery record after the tail and the task note do.
+ */
+export type ProviderSummaryRequest = { readonly instructions: string };
+type SupportProbe = (model: unknown) => unknown;
+function isProbe(value: unknown): value is SupportProbe {
+	return typeof value === "function";
+}
+/** Exported by a host that can make the block; it knows which models return one. */
+const hostSupport: unknown = Reflect.get(host, "supportsProviderSummary");
+export function hostMakesProviderSummary(model: unknown): boolean {
+	return isProbe(hostSupport) && model !== undefined && hostSupport(model) === true;
+}
+/** Measured size of a one-line block is 59 to 77 tokens; Pi's estimate does not count it. */
+export const PROVIDER_SUMMARY_TOKENS = 100;
+/**
+ * The model answers a request for a one-line summary. It refuses a request to reply with a fixed
+ * line or with the path only, and one that tells the summary to speak about "the recent messages",
+ * so the wording asks for a summary that points to the note, or to the record when there is none.
+ */
+export function providerSummaryInstructions(notePath: string | undefined): string {
+	const pointer =
+		notePath === undefined
+			? "state that the details are in the recovery record below"
+			: `point to the task note \`${notePath}\` and say to read that note and proceed from there`;
+	return `Write a summary of one line, at most 20 words: name the task in a few words, then ${pointer}. Do not mention progress, a pending step or a next step. Do not call any tools; respond with the summary text only.`;
+}
+type MessageLike = { readonly role: string };
+/**
+ * How many leading messages Pi sends exactly as the provider last saw them. With a block, those
+ * are the leading system message and the retained tail up to the record; changing, removing or
+ * reordering one makes the provider drop the reasoning of every reply after it. A tail that
+ * reaches back across an earlier rollover holds that rollover's record too, so the boundary is
+ * the last record.
+ */
+export function messagesHeldByProviderSummary(messages: readonly MessageLike[]): number {
+	const [first] = messages;
+	if (
+		first?.role !== "system" ||
+		!("providerSummary" in first) ||
+		first.providerSummary === undefined
+	) {
+		return 0;
+	}
+	const record = messages.findLastIndex((message) => message.role === "compactionSummary");
+	return record < 0 ? messages.length : record;
+}

package/src/recovery-notes.ts

@@ -172,34 +172,62 @@ function trackedNotes(
 	}
 	return [...tracked.values()].sort((a, b) => b.order - a.order);
 }
-export function renderSessionNotes(
+type NoteSources = {
+	readonly retained: ReadonlySet<string>;
+	readonly notes?: NotesRecovery | undefined;
+};
+function sessionNotes(
 	chainEntries: readonly EntryLike[],
 	allEntries: readonly EntryLike[],
 	projected: readonly ProjectedEntry[],
-	options: {
-		readonly retained: ReadonlySet<string>;
-		readonly span: RetainedSpan | undefined;
-		readonly maxChars: number;
-		readonly notes?: NotesRecovery | undefined;
-	},
-): string | undefined {
-	const { retained, span, maxChars } = options;
+	sources: NoteSources,
+): { readonly all: readonly TrackedNote[]; readonly notesDirectory: string | undefined } {
 	const collected = sessionNoteTouches({
 		branch: chainEntries,
-		allEntries: options.notes?.entries ?? allEntries,
+		allEntries: sources.notes?.entries ?? allEntries,
 		projected,
-		retained,
+		retained: sources.retained,
 	});
-	const touches = scopeRecoveryTouches(collected.touches, options.notes);
+	const touches = scopeRecoveryTouches(collected.touches, sources.notes);
 	const { defaultDir } = collected;
-	const all = trackedNotes(touches, defaultDir);
+	return {
+		all: trackedNotes(touches, defaultDir),
+		notesDirectory:
+			sources.notes === undefined ? defaultDir : scopeDirectory(sources.notes.binding),
+	};
+}
+/**
+ * The file path of the note that the record names first, when this session wrote one. The path is
+ * absolute whenever the notes directory is known, so the `read` tool opens it from any directory.
+ */
+export function primaryNotePath(
+	chainEntries: readonly EntryLike[],
+	allEntries: readonly EntryLike[],
+	projected: readonly ProjectedEntry[],
+	sources: NoteSources,
+): string | undefined {
+	const { all, notesDirectory } = sessionNotes(chainEntries, allEntries, projected, sources);
+	const primary = all.find((note) => note.kind === "written");
+	return primary === undefined
+		? undefined
+		: (pathElsewhere(primary, notesDirectory) ?? primary.absPath ?? primary.notePath);
+}
+export function renderSessionNotes(
+	chainEntries: readonly EntryLike[],
+	allEntries: readonly EntryLike[],
+	projected: readonly ProjectedEntry[],
+	options: NoteSources & {
+		readonly span: RetainedSpan | undefined;
+		readonly maxChars: number;
+	},
+): string | undefined {
+	const { span, maxChars } = options;
+	const { all, notesDirectory } = sessionNotes(chainEntries, allEntries, projected, options);
 	if (all.length === 0) {
 		return;
 	}
 	const written = all.filter((note) => note.kind === "written").slice(0, MAX_WRITTEN_NOTES);
 	const readOnly = all.filter((note) => note.kind === "read").slice(0, MAX_READ_NOTES);
-	const notesDirectory =
-		options.notes === undefined ? defaultDir : scopeDirectory(options.notes.binding);
 	const lines = [
 		...written.map((note) => formatWrittenNoteLine(note, span, notesDirectory)),
 		...readOnly.map((note) => formatReadNoteLine(note, span, notesDirectory)),

package/src/recovery.ts

@@ -9,7 +9,7 @@ import {
 	type RecoveryRecord,
 } from "./recovery-records.ts";
 import type { NotesRecovery } from "./note-evidence.ts";
-import { renderSessionNotes, type RetainedSpan } from "./recovery-notes.ts";
+import { primaryNotePath, renderSessionNotes, type RetainedSpan } from "./recovery-notes.ts";
 import {
 	recoverableToolResults,
 	type RecoveryBatch,
@@ -255,6 +255,20 @@ function rolloverPreambleWithNotes(
 	);
 	return joined([basePreamble, notesSection]);
 }
+/** The note the automatic record tells the agent to read, for text that names it outside the record. */
+export function recoveryNotePath(
+	entries: readonly EntryLike[],
+	projected: readonly ProjectedEntry[],
+	options: {
+		readonly retainedEntryIds: ReadonlySet<string>;
+		readonly notes?: NotesRecovery | undefined;
+	},
+): string | undefined {
+	return primaryNotePath(entries.slice(automaticChainStart(entries)), entries, projected, {
+		retained: options.retainedEntryIds,
+		notes: options.notes,
+	});
+}
 /** Raw owner anchors and projected tool evidence have distinct provenance and share one bounded payload. */
 export function buildAutoHandoff(
 	entries: readonly EntryLike[],

package/src/retention.ts

@@ -15,7 +15,12 @@ import {
 	type PolicyContext,
 } from "./contracts.ts";
 import type { NotesRecovery } from "./note-evidence.ts";
-import { buildAutoHandoff } from "./recovery.ts";
+import {
+	PROVIDER_SUMMARY_TOKENS,
+	providerSummaryInstructions,
+	type ProviderSummaryRequest,
+} from "./provider-summary.ts";
+import { buildAutoHandoff, recoveryNotePath } from "./recovery.ts";
 
 type RecoveryCapacity = {
 	readonly host: PolicyContext;
@@ -23,6 +28,8 @@ type RecoveryCapacity = {
 	readonly pendingMessages?: readonly MessageLike[];
 	readonly firstKeptEntryId?: string | undefined;
 	readonly notes?: NotesRecovery | undefined;
+	/** The host will ask the provider for a summary block, which needs an assistant message first in the tail. */
+	readonly providerSummary?: boolean | undefined;
 };
 type RetainedTail = {
 	readonly firstKeptEntryId?: string | undefined;
@@ -53,6 +60,19 @@ function safeStart(entry: ProjectionEntry): boolean {
 		visibleMessages(entry).some((message) => CUT_ROLES.has(message.role))
 	);
 }
+/**
+ * A provider summary block stands for the request that produced the tail's first message, so
+ * that message must be a reply the provider completed.
+ */
+function assistantStart(entry: ProjectionEntry): boolean {
+	const [first] = visibleMessages(entry);
+	return (
+		entry.sourceEntry.type !== "compaction" &&
+		first?.role === "assistant" &&
+		first.stopReason !== "error" &&
+		first.stopReason !== "aborted"
+	);
+}
 function nativeMessage(
 	message: ProjectionEntry["messages"][number],
 ): SessionMessageEntry["message"] {
@@ -129,6 +149,7 @@ function boundedTail(
 	entries: readonly ProjectionEntry[],
 	start: number,
 	maxTokens: number,
+	startsTail: (entry: ProjectionEntry) => boolean,
 ): RetainedTail {
 	const costs = entries.slice(start).map((entry) => ({
 		entry,
@@ -143,7 +164,7 @@ function boundedTail(
 	let tokens = costs.reduce((sum, { cost }) => sum + cost, 0);
 	for (const [offset, { entry, cost }] of costs.entries()) {
 		const index = start + offset;
-		if (tokens > 0 && tokens <= maxTokens && safeStart(entry)) {
+		if (tokens > 0 && tokens <= maxTokens && startsTail(entry)) {
 			const tail = entries.slice(index);
 			if (pairedTail(tail)) {
 				return {
@@ -178,7 +199,14 @@ function retainedTail(
 		(entry) => entry.sourceEntry.id === capacity.firstKeptEntryId,
 	);
 	const start = prepared >= 0 ? prepared : projectedCut(entries, keep);
-	return start < 0 ? { ids: new Set() } : boundedTail(entries, start, maxTokens);
+	return start < 0
+		? { ids: new Set() }
+		: boundedTail(
+				entries,
+				start,
+				maxTokens,
+				capacity.providerSummary === true ? assistantStart : safeStart,
+			);
 }
 /** Recent messages and recovery share half the fresh operational budget, leaving work headroom. */
 export function automaticRecovery(
@@ -186,7 +214,13 @@ export function automaticRecovery(
 	projected: readonly ProjectionEntry[],
 	capacity: RecoveryCapacity,
 	ownerQuestionRegistered: boolean,
-): { readonly handoff: string; readonly firstKeptEntryId?: string | undefined } | undefined {
+):
+	| {
+			readonly handoff: string;
+			readonly firstKeptEntryId?: string | undefined;
+			readonly providerSummary?: ProviderSummaryRequest | undefined;
+	  }
+	| undefined {
 	const payload = freshPayloadChars(
 		capacity.host,
 		capacity.toolTokens,
@@ -197,13 +231,34 @@ export function automaticRecovery(
 	if (limit < MIN_PAGE_CHARS) {
 		return undefined;
 	}
-	const retained = retainedTail(projected, capacity, Math.floor((payload - limit) / 4));
+	const asksProvider = capacity.providerSummary === true;
+	const retained = retainedTail(
+		projected,
+		capacity,
+		Math.floor((payload - limit) / 4) - (asksProvider ? PROVIDER_SUMMARY_TOKENS : 0),
+	);
 	const handoff = buildAutoHandoff(entries, projected, limit, {
 		ownerQuestionRegistered,
 		retainedEntryIds: retained.ids,
 		notes: capacity.notes,
 	});
-	return handoff.length > limit
-		? undefined
-		: { handoff, firstKeptEntryId: retained.firstKeptEntryId };
+	if (handoff.length > limit) {
+		return undefined;
+	}
+	return {
+		handoff,
+		firstKeptEntryId: retained.firstKeptEntryId,
+		// Without a tail there is no reasoning to keep, so the host is not asked for a block.
+		providerSummary:
+			!asksProvider || retained.firstKeptEntryId === undefined
+				? undefined
+				: {
+						instructions: providerSummaryInstructions(
+							recoveryNotePath(entries, projected, {
+								retainedEntryIds: retained.ids,
+								notes: capacity.notes,
+							}),
+						),
+					},
+	};
 }

package/src/rollover.ts

@@ -19,6 +19,11 @@ import {
 import { registerContextTools } from "./context-tools.ts";
 import { registerGuidance } from "./guidance.ts";
 import { safeJsonStringify } from "./message-text.ts";
+import {
+	hostMakesProviderSummary,
+	messagesHeldByProviderSummary,
+	type ProviderSummaryRequest,
+} from "./provider-summary.ts";
 import { hasRetainedRolloverMarker } from "./recovery.ts";
 import { automaticRecovery } from "./retention.ts";
 import { ResetRequests } from "./reset-requests.ts";
@@ -157,8 +162,11 @@ function registerReminderFilter(
 ): void {
 	pi.on("context_with_system", (event, ctx) => {
 		const stale = staleReminderPredicate(event.messages, ctx, policy, reminders);
-		const filtered = event.messages.some(stale)
-			? event.messages.filter((message) => !stale(message))
+		const held = messagesHeldByProviderSummary(event.messages);
+		const removable = (message: (typeof event.messages)[number], index: number) =>
+			index >= held && stale(message);
+		const filtered = event.messages.some(removable)
+			? event.messages.filter((message, index) => !removable(message, index))
 			: event.messages;
 		const ordered = chronologicalRetainedTail(filtered, ctx, stale);
 		if (ordered !== event.messages) {
@@ -167,6 +175,10 @@ function registerReminderFilter(
 		return;
 	});
 }
+/** A host without the capability ignores the field; one that has it stores why no block was made. */
+function providerSummaryField(request: ProviderSummaryRequest | undefined) {
+	return request === undefined ? {} : { providerSummary: request };
+}
 function automaticDraft(
 	pi: ExtensionAPI,
 	ctx: ExtensionContext,
@@ -175,6 +187,7 @@ function automaticDraft(
 		readonly tokensBefore: number;
 		readonly reason: string;
 		readonly firstKeptEntryId?: string | undefined;
+		readonly providerSummary?: ProviderSummaryRequest | undefined;
 	},
 ) {
 	let firstKeptEntryId = recovery.firstKeptEntryId;
@@ -192,6 +205,7 @@ function automaticDraft(
 			firstKeptEntryId,
 			tokensBefore: recovery.tokensBefore,
 			details: { posthorse: 1, reason: recovery.reason },
+			...providerSummaryField(recovery.providerSummary),
 		},
 	};
 }
@@ -280,6 +294,7 @@ function thresholdFallback(
 			toolTokens: toolTokens(),
 			pendingMessages: event.context.pendingMessages,
 			notes: capacity.notes(ctx),
+			providerSummary: hostMakesProviderSummary(ctx.model),
 		},
 		ownerQuestionRegistered,
 	);
@@ -298,6 +313,7 @@ function thresholdFallback(
 					summary: recovery.handoff,
 					firstKeptEntryId: recovery.firstKeptEntryId ?? null,
 					details: { posthorse: 1, reason: "threshold" },
+					...providerSummaryField(recovery.providerSummary),
 				},
 			],
 			continue: event.continue,
@@ -341,6 +357,8 @@ function prepareAutomatic(
 			toolTokens: capacity.toolTokens(),
 			firstKeptEntryId: event.preparation.firstKeptEntryId,
 			notes: capacity.notes(ctx),
+			// Pi makes no block at an overflow, so the tail keeps its usual start there.
+			providerSummary: event.reason !== "overflow" && hostMakesProviderSummary(ctx.model),
 		},
 		ownerQuestionRegistered,
 	);