pi-posthorse 0.10.22 → 0.10.25

package/index.ts

@@ -12,7 +12,9 @@ import {
 import { registerPosthorseMessages } from "./ui.ts";
 import { policySnapshot } from "./src/budget.ts";
 import type { CompactionPolicy, PolicyReader } from "./src/contracts.ts";
+import { createWindowGuidance } from "./src/guidance.ts";
 import { registerHistory } from "./src/history.ts";
+import { toolFacts } from "./src/host.ts";
 import { safeJsonStringify } from "./src/message-text.ts";
 import { registerNotes } from "./src/notes.ts";
 import { createNotesStore } from "./src/note-store.ts";
@@ -21,9 +23,8 @@ import { PageReservations } from "./src/paging.ts";
 import { registerRollover } from "./src/rollover.ts";
 
 function activeToolTokens(pi: ExtensionAPI): number {
-	const active = new Set(pi.getActiveTools());
-	return pi
-		.getAllTools()
+	const { active, tools } = toolFacts(pi);
+	return tools
 		.filter((tool) => active.has(tool.name))
 		.reduce(
 			(total, tool) =>
@@ -44,8 +45,11 @@ export function createPosthorse(getPolicy?: PolicyReader): (pi: ExtensionAPI) =>
 		const readPolicy: PolicyReader =
 			getPolicy ??
 			((ctx) => SettingsManager.inMemory(pi.getSettings()).getCompactionSettings(ctx.model));
+		const guidance = createWindowGuidance(pi);
 		const policy = (ctx: ExtensionContext, livePolicy?: CompactionPolicy) =>
-			policySnapshot(ctx, readPolicy, livePolicy);
+			policySnapshot(ctx, readPolicy, livePolicy, (target, host) =>
+				guidance.resolve(target, host),
+			);
 		const toolTokens = () => activeToolTokens(pi);
 		const pages = new PageReservations(toolTokens);
 		registerPosthorseMessages(pi);
@@ -55,6 +59,7 @@ export function createPosthorse(getPolicy?: PolicyReader): (pi: ExtensionAPI) =>
 				pages.reset();
 			},
 			notes: (ctx) => notes.recovery(ctx),
+			guidance,
 		});
 		pi.on("session_start", async (_event, ctx) => {
 			await notes.get(ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-posthorse",
-	"version": "0.10.22",
+	"version": "0.10.25",
 	"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/boundary.ts

@@ -0,0 +1,95 @@
+import { AUTO_HANDOFF_PREFIX, isRecord, type EntryLike, type ProjectedEntry } from "./contracts.ts";
+
+export type BoundaryKind = "fork" | "native" | "automatic" | "explicit" | "posthorse";
+/** Everything the app derives from one persisted context boundary, decided in one place. */
+export type Boundary = {
+	readonly kind: BoundaryKind;
+	/** Counts as a Posthorse window: labels, reminder windows, and note provenance. */
+	readonly window: boolean;
+	/** An automatic recovery record that walks through earlier windows continue past. */
+	readonly chainsAncestry: boolean;
+	/** Starts a new guidance epoch; a provider summary block keeps the previous one. */
+	readonly freshGuidance: boolean;
+};
+
+export function windowHandoff(entry: EntryLike | undefined): string | undefined {
+	return entry?.type === "compaction" ? entry.summary : entry?.handoff;
+}
+/** An automatic recovery record opens with this prefix; an earlier window's walk may continue past it. */
+function automaticHandoff(entry: EntryLike): boolean {
+	return windowHandoff(entry)?.trim().startsWith(AUTO_HANDOFF_PREFIX) === true;
+}
+/**
+ * A compaction with a provider summary block carries forward the previous window's leading system
+ * message unchanged, so its guidance section must stay locked to that earlier epoch too.
+ */
+function providerSummaryBlock(entry: EntryLike): boolean {
+	return (
+		entry.type === "compaction" &&
+		isRecord(entry.providerSummary) &&
+		isRecord(entry.providerSummary.block)
+	);
+}
+function compactionKind(details: Readonly<Record<string, unknown>>): BoundaryKind {
+	if (details.reason === "threshold" || details.reason === "overflow") {
+		return "automatic";
+	}
+	return details.reason === "explicit" ? "explicit" : "posthorse";
+}
+export function classifyBoundary(entry?: EntryLike): Boundary | undefined {
+	if (entry?.type === "context_window") {
+		return {
+			kind: "fork",
+			window: true,
+			chainsAncestry: automaticHandoff(entry),
+			freshGuidance: true,
+		};
+	}
+	if (entry?.type !== "compaction") {
+		return undefined;
+	}
+	const details = isRecord(entry.details) ? entry.details : undefined;
+	const freshGuidance = !providerSummaryBlock(entry);
+	if (details?.posthorse !== 1) {
+		return { kind: "native", window: false, chainsAncestry: false, freshGuidance };
+	}
+	const kind = compactionKind(details);
+	return {
+		kind,
+		window: true,
+		chainsAncestry: kind === "automatic" && automaticHandoff(entry),
+		freshGuidance,
+	};
+}
+export function isWindow(entry: EntryLike): boolean {
+	return classifyBoundary(entry)?.window === true;
+}
+export function startsFreshGuidanceEpoch(entry: EntryLike): boolean {
+	return classifyBoundary(entry)?.freshGuidance === true;
+}
+export function chainsAncestry(entry?: EntryLike): boolean {
+	return classifyBoundary(entry)?.chainsAncestry === true;
+}
+/** The boundary already applied to a projection: a compaction with a visible tail. -1 when none. */
+export function activeBoundaryIndex(projected: readonly ProjectedEntry[]): number {
+	return projected.findIndex(
+		(entry) => entry.sourceEntry.type === "compaction" && entry.messages.length > 0,
+	);
+}
+/** First active branch entry, including tails retained by Pi's own /compact. */
+export function contextStart(entries: readonly EntryLike[]): {
+	start: number;
+	boundary?: EntryLike;
+} {
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i];
+		if (entry?.type === "context_window") {
+			return { start: i + 1, boundary: entry };
+		}
+		if (entry?.type === "compaction") {
+			const kept = entries.findIndex((candidate) => candidate.id === entry.firstKeptEntryId);
+			return { start: kept >= 0 ? kept : i + 1, boundary: entry };
+		}
+	}
+	return { start: 0 };
+}

package/src/budget.ts

@@ -13,24 +13,41 @@ import {
 import { imagesOf, textOf } from "./message-text.ts";
 
 const MIN_USABLE_TOKENS = Math.ceil(MAX_HANDOFF_CHARS / 4) * 2;
+export type GuidanceTools = {
+	readonly newContext: boolean;
+	readonly getContextRemaining: boolean;
+};
+export const ALL_GUIDANCE_TOOLS: GuidanceTools = {
+	newContext: true,
+	getContextRemaining: true,
+};
 export type Budget = {
 	readonly contextWindow: number;
 	readonly reserveTokens: number;
-	readonly enabled: boolean;
+	/** One classification of how Posthorse may use this capacity. */
+	readonly state: BudgetState;
 	readonly usable: number;
 	readonly rolloverAt: number;
-	readonly supported: boolean;
 };
+export type BudgetState = "disabled" | "unsupported" | "enabled";
+function budgetState(enabled: boolean, usable: number): BudgetState {
+	if (!enabled) {
+		return "disabled";
+	}
+	return usable >= MIN_USABLE_TOKENS ? "enabled" : "unsupported";
+}
 /** A synchronous evaluation owns one snapshot; never carry it across an await. */
 export function policySnapshot(
 	ctx: ExtensionContext,
 	getPolicy: PolicyReader,
 	livePolicy?: CompactionPolicy,
+	resolveGuidance?: (ctx: ExtensionContext, host: PolicyContext) => string,
 ): PolicyContext {
 	let usageRead = false;
 	let usage: ContextUsage | undefined;
 	let settings: CompactionPolicy | undefined;
-	return {
+	let guidance: string | undefined;
+	const host: PolicyContext = {
 		getCompactionSettings: () => {
 			settings ??= { ...(livePolicy ?? getPolicy(ctx)) };
 			return settings;
@@ -43,7 +60,13 @@ export function policySnapshot(
 			return usage;
 		},
 		getSystemPrompt: () => ctx.getSystemPrompt(),
+		getGuidance: () => {
+			guidance ??=
+				resolveGuidance !== undefined ? resolveGuidance(ctx, host) : buildGuidance(host);
+			return guidance;
+		},
 	};
+	return host;
 }
 export function budgetFor(
 	ctx: PolicyContext,
@@ -57,64 +80,105 @@ export function budgetFor(
 	return {
 		contextWindow,
 		reserveTokens,
-		enabled,
+		state: budgetState(enabled, usable),
 		usable,
 		rolloverAt: usable + 1,
-		supported: !enabled || usable >= MIN_USABLE_TOKENS,
 	};
 }
-export function unsupportedMessage(budget: Budget): string {
+export function budgetGuidanceKey(ctx: PolicyContext): string {
+	const budget = budgetFor(ctx);
+	if (budget === undefined) {
+		return ctx.getCompactionSettings().enabled ? "1:unknown" : "0:unknown";
+	}
+	return budget.state === "disabled"
+		? `0:${budget.contextWindow}`
+		: `1:${budget.contextWindow}:${budget.reserveTokens}`;
+}
+export function unsupportedMessage(budget: Budget, newContextAvailable = true): string {
 	const n = (value: number) => value.toLocaleString("en-US");
-	return `Posthorse: unsupported configuration. The model's context window (${n(budget.contextWindow)} tokens) minus Pi's compaction.reserveTokens (${n(budget.reserveTokens)}) leaves ${n(budget.usable)} usable tokens; Posthorse needs at least ${n(MIN_USABLE_TOKENS)}. Automatic Posthorse rollover and checkpoint reminders are off for this model, so Pi's own compaction applies. Lower compaction.reserveTokens in Pi settings or use a larger-context model. new_context remains available with a model-aware handoff limit.`;
+	const reset = newContextAvailable
+		? " new_context remains available with a model-aware handoff limit."
+		: "";
+	return `Posthorse: unsupported configuration. The model's context window (${n(budget.contextWindow)} tokens) minus Pi's compaction.reserveTokens (${n(budget.reserveTokens)}) leaves ${n(budget.usable)} usable tokens; Posthorse needs at least ${n(MIN_USABLE_TOKENS)}. Automatic Posthorse rollover and checkpoint reminders are off for this model, so Pi's own compaction applies. Lower compaction.reserveTokens in Pi settings or use a larger-context model.${reset}`;
 }
-function automaticGuidance(budget: Budget | undefined, enabled: boolean): string {
+function automaticGuidance(
+	budget: Budget | undefined,
+	enabled: boolean,
+	tools: GuidanceTools,
+): string {
 	if (!enabled) {
-		return "Pi compaction is disabled in the available settings, so Posthorse sends no checkpoint reminder. new_context remains available.";
+		const reset = tools.newContext ? " new_context remains available." : "";
+		return `Pi compaction is disabled in the available settings, so Posthorse sends no checkpoint reminder.${reset}`;
 	}
-	if (budget !== undefined && !budget.supported) {
-		return unsupportedMessage(budget);
+	if (budget?.state === "unsupported") {
+		return unsupportedMessage(budget, tools.newContext);
 	}
 	const line =
 		budget === undefined
 			? ""
 			: `The rollover line is ${budget.rolloverAt.toLocaleString("en-US")} tokens used. `;
+	const reset = tools.newContext ? " new_context is an optional clean reset." : "";
 	return `Pi rolls context over automatically, so the context window is not a deadline. Do not reduce scope, skip steps or verification, or write a final summary because rollover is near, and do not wait for the user to say "continue". Finish when the requested work and its verification are complete, or report a genuine blocker.
-${line}Rollover keeps a recent-message tail without summarizing. One task-note reminder may arrive at the end of a working turn near the line: update the note only if it is stale, or write one if the task has none, then continue with the next step in the same run. new_context is an optional clean reset.`;
+${line}Rollover keeps a recent-message tail without summarizing. One task-note reminder may arrive at the end of a working turn near the line: update the note only if it is stale, or write one if the task has none, then continue with the next step in the same run.${reset}`;
 }
-export function buildGuidance(ctx: PolicyContext): string {
+export function buildGuidance(
+	ctx: PolicyContext,
+	tools: GuidanceTools = ALL_GUIDANCE_TOOLS,
+): string {
 	const budget = budgetFor(ctx);
-	const enabled = budget?.enabled ?? ctx.getCompactionSettings().enabled;
+	const enabled =
+		budget === undefined ? ctx.getCompactionSettings().enabled : budget.state !== "disabled";
 	const capacity =
 		budget === undefined
 			? "Configured context capacity is unknown."
 			: `Configured context capacity: ${budget.contextWindow.toLocaleString("en-US")} tokens (not remaining space).`;
+	const checkRemaining = tools.getContextRemaining
+		? " Before reporting a remaining-token count or changing your work plan because of context limits, call get_context_remaining."
+		: "";
 	return `## Automatic context management (Posthorse)
-${automaticGuidance(budget, enabled)}
-${capacity} Do not guess capacity or remaining space from response-token or reasoning limits. Before reporting a remaining-token count or changing your work plan because of context limits, call get_context_remaining. If usage is unknown, report it as unknown. No routine budget checks are needed.
+${automaticGuidance(budget, enabled, tools)}
+${capacity} Do not guess capacity or remaining space from response-token or reasoning limits.${checkRemaining} If usage is unknown, report it as unknown. No routine budget checks are needed.
 After a rollover, earlier conversation stays in history. Restore notes and todos, then verify live state before stateful or external work; automatic handoffs record inputs, not progress.
 Keep one concise current-state note per task: goal, progress, decisions, and next steps. Preserve decisions and safety constraints, link fuller evidence instead of copying it, and edit only changed sections.`;
 }
-/** ponytail: native estimates omit request-local guidance; reserve it until post-transform usage is exposed. */
-export function guidanceTokens(ctx: PolicyContext): number {
+export function guidanceFor(ctx: PolicyContext): string {
+	return ctx.getGuidance !== undefined ? ctx.getGuidance() : buildGuidance(ctx);
+}
+function guidanceTokenCount(guidance: string): number {
 	return estimateTokens({
 		role: "system",
-		content: `<posthorse>\n${buildGuidance(ctx)}\n</posthorse>`,
+		content: `<posthorse>\n${guidance}\n</posthorse>`,
 		timestamp: 0,
 	});
 }
+/** ponytail: native estimates omit request-local guidance; reserve it until post-transform usage is exposed. */
+export function guidanceTokens(ctx: PolicyContext): number {
+	return guidanceTokenCount(guidanceFor(ctx));
+}
+/**
+ * Which guidance the reservation subtracts: the text rebuilt for the next request, or the host's
+ * effective text that is already in the prompt.
+ */
+export type GuidanceReservation = "rebuild" | "effective";
 /** Half the fresh capacity after prompt/tool/input overhead remains for continued work. */
 export function freshPayloadChars(
 	ctx: PolicyContext,
 	toolTokens: number,
-	pendingMessages: readonly MessageLike[] = [],
-	cap = MAX_HANDOFF_CHARS,
+	options: {
+		readonly pendingMessages?: readonly MessageLike[] | undefined;
+		readonly cap?: number | undefined;
+		readonly guidance?: GuidanceReservation | undefined;
+	} = {},
 ): number {
+	const { pendingMessages = [], cap = MAX_HANDOFF_CHARS, guidance = "rebuild" } = options;
 	const budget = budgetFor(ctx);
 	if (budget === undefined) {
 		return cap;
 	}
-	const line = budget.enabled && budget.supported ? budget.rolloverAt : budget.contextWindow;
-	const promptTokens = Math.ceil(ctx.getSystemPrompt().length / 4) + guidanceTokens(ctx);
+	const line = budget.state === "enabled" ? budget.rolloverAt : budget.contextWindow;
+	const reservedGuidance =
+		guidance === "rebuild" ? guidanceTokenCount(buildGuidance(ctx)) : guidanceTokens(ctx);
+	const promptTokens = Math.ceil(ctx.getSystemPrompt().length / 4) + reservedGuidance;
 	const pendingTokens = pendingMessages.reduce(
 		(total, message) =>
 			total +
@@ -133,10 +197,13 @@ export function freshPayloadChars(
 export function pageCapacity(ctx: PolicyContext, toolTokens: () => number): number {
 	const usage = ctx.getContextUsage();
 	if (usage === undefined || usage.tokens === null) {
-		return freshPayloadChars(ctx, toolTokens(), [], MAX_PAGE_CHARS) / 4 + PAGE_MARGIN_TOKENS;
+		return (
+			freshPayloadChars(ctx, toolTokens(), { cap: MAX_PAGE_CHARS, guidance: "effective" }) /
+				4 +
+			PAGE_MARGIN_TOKENS
+		);
 	}
 	const budget = budgetFor(ctx, usage.contextWindow);
-	const line =
-		budget?.enabled === true && budget.supported ? budget.rolloverAt : usage.contextWindow;
+	const line = budget?.state === "enabled" ? budget.rolloverAt : usage.contextWindow;
 	return line - usage.tokens - guidanceTokens(ctx);
 }

package/src/context-tools.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { Type } from "typebox";
 import { toolCards, type PosthorseDisplay } from "../ui.ts";
 import { budgetFor, freshPayloadChars, unsupportedMessage, type Budget } from "./budget.ts";
+import { activeGuidanceTools } from "./guidance.ts";
 import {
 	EMPTY_HANDOFF,
 	MAX_HANDOFF_CHARS,
@@ -11,12 +12,9 @@ import {
 } from "./contracts.ts";
 
 function rolloverStatus(budget: Budget | undefined): "disabled" | "enabled" | "unsupported" {
-	if (budget?.enabled !== true) {
-		return "disabled";
-	}
-	return budget.supported ? "enabled" : "unsupported";
+	return budget?.state ?? "disabled";
 }
-function contextReport(host: PolicyContext): TextResult {
+function contextReport(host: PolicyContext, newContextAvailable: boolean): TextResult {
 	const usage = host.getContextUsage();
 	if (usage === undefined || usage.tokens === null) {
 		return textResult("Context usage is not known until the next model response.", [], {
@@ -33,15 +31,19 @@ function contextReport(host: PolicyContext): TextResult {
 		rolloverAt: budget?.rolloverAt,
 	};
 	const configured = `≈${n(Math.max(0, usage.contextWindow - usage.tokens))} tokens until the configured context limit (${n(usage.tokens)}/${n(usage.contextWindow)} used, ${Math.round(usage.percent ?? 0)}%). Best available native estimate.`;
-	if (budget?.enabled !== true) {
+	if (budget === undefined || budget.state === "disabled") {
 		return textResult(
 			`Automatic rollover is disabled in the available settings (Pi compaction.enabled=false). ${configured}`,
 			[],
 			display,
 		);
 	}
-	if (!budget.supported) {
-		return textResult(`${unsupportedMessage(budget)} ${configured}`, [], display);
+	if (budget.state === "unsupported") {
+		return textResult(
+			`${unsupportedMessage(budget, newContextAvailable)} ${configured}`,
+			[],
+			display,
+		);
 	}
 	return textResult(
 		`≈${n(Math.max(0, budget.rolloverAt - usage.tokens))} tokens until automatic rollover (line at ${n(budget.rolloverAt)}); ${configured}`,
@@ -97,7 +99,7 @@ export function registerContextTools(
 			"verify remaining context before reporting a token count or changing plans because of context limits",
 		parameters: Type.Object({}),
 		async execute(...[, , , , ctx]) {
-			return contextReport(policy(ctx));
+			return contextReport(policy(ctx), activeGuidanceTools(pi).newContext);
 		},
 	});
 }

package/src/contracts.ts

@@ -17,6 +17,7 @@ export type PolicyContext = {
 	readonly getCompactionSettings: () => CompactionPolicy;
 	readonly getContextUsage: () => ContextUsage | undefined;
 	readonly getSystemPrompt: () => string;
+	readonly getGuidance?: () => string;
 };
 export type PolicyReader = (ctx: ExtensionContext) => CompactionPolicy;
 export type SnapshotReader = (
@@ -70,6 +71,7 @@ export type EntryLike = {
 	readonly parentSession?: string | undefined;
 	readonly handoff?: string | undefined;
 	readonly firstKeptEntryId?: string | null | undefined;
+	readonly providerSummary?: unknown;
 	readonly targetId?: string | undefined;
 	readonly replacement?: { readonly content: unknown } | null | undefined;
 };
@@ -116,6 +118,10 @@ export function unknownArray(value: unknown): readonly unknown[] | undefined {
 export function optionalString(value: unknown): string | undefined {
 	return typeof value === "string" ? value : undefined;
 }
+/** Some models send every optional argument; an empty string means the argument was omitted. */
+export function presentText(value: unknown): string | undefined {
+	return typeof value === "string" && value !== "" ? value : undefined;
+}
 export function requireValue(value: string | undefined, name: string, op: string): string {
 	if (value === undefined || value === "") {
 		throw new Error(`"${name}" is required for op "${op}".`);

package/src/epoch-cache.ts

@@ -0,0 +1,50 @@
+import { sessionIdentity, type SessionHost, type SessionIdentity } from "./host.ts";
+
+/** A cached value with the session state it was computed from. */
+export type EpochValue<Value> = {
+	readonly identity: SessionIdentity;
+	readonly value: Value;
+};
+export type EpochCache<Value> = {
+	readonly read: (ctx: SessionContext) => Value;
+	readonly reset: () => void;
+};
+export type SessionContext = { readonly sessionManager: SessionHost };
+
+function sameSession(left: SessionIdentity, right: SessionIdentity): boolean {
+	return left.sessionId === right.sessionId && left.file === right.file;
+}
+/**
+ * Caches one session fact for the current leaf. A new leaf recomputes unless its walk reaches the
+ * cached leaf entry itself: entry identity, not a reusable id, certifies an append-only extension.
+ */
+export function createEpochCache<Value>(
+	compute: (
+		ctx: SessionContext,
+		identity: SessionIdentity,
+		previous: EpochValue<Value> | undefined,
+	) => Value,
+): EpochCache<Value> {
+	let cached: (EpochValue<Value> & { readonly manager: object }) | undefined;
+	return {
+		reset: () => {
+			cached = undefined;
+		},
+		read: (ctx) => {
+			const manager: object = ctx.sessionManager;
+			const identity = sessionIdentity(ctx.sessionManager);
+			const previous =
+				cached !== undefined &&
+				cached.manager === manager &&
+				sameSession(cached.identity, identity)
+					? cached
+					: undefined;
+			if (previous !== undefined && previous.identity.leaf === identity.leaf) {
+				return previous.value;
+			}
+			const value = compute(ctx, identity, previous);
+			cached = { manager, identity, value };
+			return value;
+		},
+	};
+}

package/src/guidance.ts

@@ -1,8 +1,186 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { buildGuidance } from "./budget.ts";
-import type { SnapshotReader } from "./contracts.ts";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import { Check } from "typebox/value";
+import {
+	ALL_GUIDANCE_TOOLS,
+	budgetGuidanceKey,
+	buildGuidance,
+	type GuidanceTools,
+} from "./budget.ts";
+import type { EntryLike, PolicyContext, SnapshotReader } from "./contracts.ts";
+import { startsFreshGuidanceEpoch } from "./boundary.ts";
+import { createEpochCache, type EpochValue } from "./epoch-cache.ts";
+import { sessionEntry, toolFacts, type SessionHost, type SessionIdentity } from "./host.ts";
 
-export function registerGuidance(pi: ExtensionAPI, policy: SnapshotReader): void {
+export const WINDOW_GUIDANCE_TYPE = "posthorse-window-guidance";
+const guidanceRecordSchema = Type.Object({
+	version: Type.Literal(1),
+	budgetKey: Type.String(),
+	text: Type.String(),
+	tools: Type.Object({
+		newContext: Type.Boolean(),
+		getContextRemaining: Type.Boolean(),
+	}),
+});
+type WindowGuidanceRecord = Static<typeof guidanceRecordSchema>;
+type MemoryEpoch = {
+	readonly byBudget: Map<string, string>;
+	tools: GuidanceTools | undefined;
+};
+type GuidanceEpoch = {
+	readonly anchorKey: string;
+	readonly byBudget: ReadonlyMap<string, string>;
+	readonly tools: GuidanceTools | undefined;
+};
+export type WindowGuidance = {
+	readonly resolve: (ctx: ExtensionContext, host: PolicyContext) => string;
+	readonly deliver: (ctx: ExtensionContext, host: PolicyContext) => string;
+	readonly reset: () => void;
+};
+
+export function activeGuidanceTools(pi: ExtensionAPI): GuidanceTools {
+	const { activeUnnamespaced } = toolFacts(pi);
+	return {
+		newContext: activeUnnamespaced.has("new_context"),
+		getContextRemaining: activeUnnamespaced.has("get_context_remaining"),
+	};
+}
+function collectGuidanceEntries(
+	entries: readonly EntryLike[],
+	baseByBudget?: ReadonlyMap<string, string>,
+	baseTools?: GuidanceTools,
+): { readonly byBudget: Map<string, string>; readonly tools: GuidanceTools | undefined } {
+	const byBudget = new Map<string, string>(baseByBudget);
+	let tools = baseTools;
+	for (const entry of entries) {
+		if (
+			entry.type === "custom" &&
+			entry.customType === WINDOW_GUIDANCE_TYPE &&
+			Check(guidanceRecordSchema, entry.data)
+		) {
+			byBudget.set(entry.data.budgetKey, entry.data.text);
+			tools ??= entry.data.tools;
+		}
+	}
+	return { byBudget, tools };
+}
+function withMemoryEpoch(
+	collected: {
+		readonly byBudget: Map<string, string>;
+		readonly tools: GuidanceTools | undefined;
+	},
+	memory: MemoryEpoch | undefined,
+): { readonly byBudget: ReadonlyMap<string, string>; readonly tools: GuidanceTools | undefined } {
+	if (memory === undefined) {
+		return collected;
+	}
+	const merged = new Map(collected.byBudget);
+	for (const [key, text] of memory.byBudget) {
+		if (!merged.has(key)) {
+			merged.set(key, text);
+		}
+	}
+	return { byBudget: merged, tools: collected.tools ?? memory.tools };
+}
+function scanGuidanceEpoch(
+	manager: SessionHost,
+	identity: SessionIdentity,
+	previous: EpochValue<GuidanceEpoch> | undefined,
+	memoryByEpoch: ReadonlyMap<string, MemoryEpoch> | undefined,
+): GuidanceEpoch {
+	const reversed: EntryLike[] = [];
+	let anchor: EntryLike | undefined;
+	for (
+		let entry = identity.leaf;
+		entry !== undefined;
+		entry = sessionEntry(manager, entry.parentId)
+	) {
+		if (previous !== undefined && previous.identity.leaf === entry) {
+			const collected = collectGuidanceEntries(
+				reversed.reverse(),
+				previous.value.byBudget,
+				previous.value.tools,
+			);
+			return {
+				anchorKey: previous.value.anchorKey,
+				...withMemoryEpoch(collected, memoryByEpoch?.get(previous.value.anchorKey)),
+			};
+		}
+		if (startsFreshGuidanceEpoch(entry)) {
+			anchor = entry;
+			break;
+		}
+		reversed.push(entry);
+	}
+	const anchorKey =
+		anchor === undefined
+			? `${identity.sessionId}:root`
+			: `${identity.sessionId}:${anchor.id ?? "boundary"}`;
+	const collected = collectGuidanceEntries(reversed.reverse());
+	return {
+		anchorKey,
+		...withMemoryEpoch(collected, memoryByEpoch?.get(anchorKey)),
+	};
+}
+export function createWindowGuidance(pi: ExtensionAPI): WindowGuidance {
+	let memoryByManager = new WeakMap<object, Map<string, MemoryEpoch>>();
+	const epochs = createEpochCache<GuidanceEpoch>((ctx, identity, previous) =>
+		scanGuidanceEpoch(
+			ctx.sessionManager,
+			identity,
+			previous,
+			memoryByManager.get(ctx.sessionManager),
+		),
+	);
+	return {
+		resolve(ctx, host) {
+			const epoch = epochs.read(ctx);
+			const key = budgetGuidanceKey(host);
+			return (
+				epoch.byBudget.get(key) ?? buildGuidance(host, epoch.tools ?? ALL_GUIDANCE_TOOLS)
+			);
+		},
+		deliver(ctx, host) {
+			const epoch = epochs.read(ctx);
+			const key = budgetGuidanceKey(host);
+			const existing = epoch.byBudget.get(key);
+			if (existing !== undefined) {
+				return existing;
+			}
+			const tools = epoch.tools ?? activeGuidanceTools(pi);
+			const text = buildGuidance(host, tools);
+			let byEpoch = memoryByManager.get(ctx.sessionManager);
+			if (byEpoch === undefined) {
+				byEpoch = new Map();
+				memoryByManager.set(ctx.sessionManager, byEpoch);
+			}
+			let memory = byEpoch.get(epoch.anchorKey);
+			if (memory === undefined) {
+				memory = { byBudget: new Map(), tools };
+				byEpoch.set(epoch.anchorKey, memory);
+			}
+			memory.byBudget.set(key, text);
+			memory.tools ??= tools;
+			epochs.reset();
+			pi.appendEntry(WINDOW_GUIDANCE_TYPE, {
+				version: 1,
+				budgetKey: key,
+				text,
+				tools,
+			} satisfies WindowGuidanceRecord);
+			return text;
+		},
+		reset() {
+			epochs.reset();
+			memoryByManager = new WeakMap();
+		},
+	};
+}
+export function registerGuidance(
+	pi: ExtensionAPI,
+	policy: SnapshotReader,
+	windowGuidance: WindowGuidance,
+): void {
 	let promptOptions: { readonly forceSystemPrompt?: string } | undefined;
 	pi.on("before_agent_start", (event) => {
 		promptOptions = event.systemPromptOptions;
@@ -12,7 +190,7 @@ export function registerGuidance(pi: ExtensionAPI, policy: SnapshotReader): void
 		promptOptions = undefined;
 	});
 	pi.on("context_with_system", (event, ctx) => {
-		const guidance = buildGuidance(policy(ctx));
+		const guidance = windowGuidance.deliver(ctx, policy(ctx));
 		const system =
 			event.messages.findLast(
 				(message) =>