pi-openai-toolkit 0.15.1 → 0.17.0

package/src/extension-runtime.ts

@@ -1,7 +1,7 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type {
 	BeforeProviderRequestEvent,
-	ContextEvent,
+	ContextWithSystemEvent,
 	CompactionResult,
 	ExtensionAPI,
 	ExtensionContext,
@@ -19,6 +19,7 @@ import {
 import { routeContextNamespaceToolMessage } from "./context-management/namespace-tools";
 import { loadHistoryNotesThreadHint } from "./context-management/history-notes";
 import { CodexContextWindowManager } from "./context-management/window-manager";
+import { ManagedManualCompact } from "./context-management/manual-compact";
 import {
 	BULK_CLIFF_RATIO,
 	decideBulkCliffAction,
@@ -32,6 +33,7 @@ import {
 import { writeDebugArtifact, writeReplayFailureArtifact } from "./debug";
 import {
 	COMPACTION_CHECKPOINT_PROVENANCE_UNAVAILABLE,
+	COMPACTION_CHECKPOINT_CONTEXT_EDITED,
 	COMPACTION_PROJECTION_UNAVAILABLE,
 	COMPACTION_SESSION_CONTEXT_UNAVAILABLE,
 	COMPACTION_PROJECTED_CONTEXT_UNAVAILABLE,
@@ -49,6 +51,7 @@ import {
 import { runNativeFallbackCompaction } from "./native-fallback";
 import {
 	rewriteResponsesPayloadWithNativeReplay,
+	hasInvalidatedCompactionContext,
 	removeNativeCompactionRetainedMessages,
 	serializeLiveTailToResponsesInput,
 } from "./payload-rewrite";
@@ -110,6 +113,7 @@ type CompactionDependencies = {
 	remoteCompact: typeof executeRemoteV2Compaction;
 	nativeFallback: typeof runNativeFallbackCompaction;
 	contextWindows: CodexContextWindowManager;
+	manualCompact?: ManagedManualCompact;
 	/** Test seam for the same ordered projection exposed by the Pi host patch. */
 	projectCompactionContext?: CompactionContextProjection;
 	piContextHookPatch: PiContextHookPatchResult;
@@ -258,22 +262,11 @@ function findLatestProjectedCompactionSummaryIndex(
 	return -1;
 }
 
-type SessionManagerWithOptionalContext = ExtensionContext["sessionManager"] & {
-	buildSessionContext?: () => { messages?: readonly AgentMessage[] };
-};
-
 function readSessionContextMessages(ctx: ExtensionContext): AgentMessage[] | undefined {
-	const sessionManager = ctx.sessionManager as SessionManagerWithOptionalContext;
-	if (typeof sessionManager.buildSessionContext !== "function") {
-		return undefined;
-	}
-
 	try {
-		const sessionContext = sessionManager.buildSessionContext();
-		if (!sessionContext || !Array.isArray(sessionContext.messages)) {
-			return undefined;
-		}
-		return structuredClone([...sessionContext.messages]);
+		const projection = ctx.sessionManager.buildSessionProjection();
+		if (!projection || !Array.isArray(projection.messages)) return undefined;
+		return structuredClone(projection.messages);
 	} catch {
 		return undefined;
 	}
@@ -337,6 +330,9 @@ async function runResponsesNativeCompact(
 	let requestSource: "session-context" | "non-native-session-context" | "latest-native-replay";
 	let request: NativeCompactionRequestBody;
 	if (latestNativeCompaction.ok) {
+		if (hasInvalidatedCompactionContext(branchEntries, latestNativeCompaction.entry.id)) {
+			return { outcome: "unprojected-input", reason: COMPACTION_CHECKPOINT_CONTEXT_EDITED };
+		}
 		const details = latestNativeCompaction.entry.details;
 		if (!details) {
 			return { outcome: "failed" };
@@ -599,6 +595,10 @@ async function handleSessionBeforeCompact(
 		if (await remoteContextActive(ctx, config)) {
 			try {
 				dependencies.contextWindows.synchronize(ctx);
+				if (event.reason === "manual" && dependencies.manualCompact && !dependencies.manualCompact.isMaintenance) {
+					await dependencies.manualCompact.request(event, ctx, resolved);
+					return { cancel: true };
+				}
 				return dependencies.contextWindows.prepareCompaction(event);
 			} catch {
 				notifyRemoteContextFailure(ctx, "malformed-window-state");
@@ -652,7 +652,9 @@ async function handleSessionBeforeCompact(
 			return { cancel: true };
 		}
 		if (responsesOutcome.outcome === "unprojected-input") {
-			const message = responsesOutcome.reason === COMPACTION_PROJECTION_UNAVAILABLE
+			const message = responsesOutcome.reason === COMPACTION_CHECKPOINT_CONTEXT_EDITED
+				? "A context edit changed history sealed in the opaque checkpoint. Start a new session or navigate before that checkpoint; its encrypted content cannot be selectively rewritten."
+				: responsesOutcome.reason === COMPACTION_PROJECTION_UNAVAILABLE
 				? "Pi's ordered context-hook projection is unavailable; Remote V2 was not sent raw session history."
 				: responsesOutcome.reason === COMPACTION_SESSION_CONTEXT_UNAVAILABLE
 					? "Pi did not provide the current session context required by its context-hook projection."
@@ -674,7 +676,7 @@ async function handleSessionBeforeCompact(
 			);
 			notifyWarning(
 				ctx,
-				`Remote V2 compaction cancelled (${responsesOutcome.reason}); ${message} Keep the context-source setting aligned with the checkpoint or choose legacy mode explicitly.`,
+				`Remote V2 compaction cancelled (${responsesOutcome.reason}); ${message} The existing checkpoint and session history were left unchanged.`,
 			);
 			return { cancel: true };
 		}
@@ -783,6 +785,7 @@ async function handleWindowBulk(
 	loadConfig: typeof loadToolkitConfig,
 	trigger: "model-switch" | "turn-end",
 	resolved = contextOperation(loadConfig, ctx),
+	beginMaintenance?: () => () => void,
 ): Promise<void> {
 	requireContextPolicy(resolved, ctx);
 	const compaction = resolved.config.compaction;
@@ -830,15 +833,20 @@ async function handleWindowBulk(
 
 	notifyWarning(ctx, `${gap} to ${modelKey}, past ${Math.round(BULK_CLIFF_RATIO * 100)}% of its window; compacting the retired windows first.`);
 	if (typeof ctx.compact !== "function") return;
-	ctx.compact({
-		onError: (error: Error) => {
-			notifyWarning(ctx, `automatic boundary compaction failed: ${error.message}`);
-		},
-	});
+	const done = beginMaintenance?.();
+	try {
+		ctx.compact({
+			onComplete: () => done?.(),
+			onError: (error: Error) => {
+				done?.();
+				notifyWarning(ctx, `automatic boundary compaction failed: ${error.message}`);
+			},
+		});
+	} catch (error) { done?.(); throw error; }
 }
 
 async function handleContextInternal(
-	event: ContextEvent,
+	event: ContextWithSystemEvent,
 	ctx: ExtensionContext,
 	pi: ExtensionAPI,
 	loadConfig: typeof loadToolkitConfig,
@@ -941,7 +949,7 @@ async function handleContextInternal(
  * caught exception for a successful projection.
  */
 async function handleContext(
-	event: ContextEvent,
+	event: ContextWithSystemEvent,
 	ctx: ExtensionContext,
 	pi: ExtensionAPI,
 	loadConfig: typeof loadToolkitConfig,
@@ -1169,12 +1177,14 @@ export default function registerCompactionExtension(
 	const contextWindows = overrides.contextWindows ?? new CodexContextWindowManager((ctx, signal, gatewayModels) =>
 		loadHistoryNotesThreadHint(ctx, signal, gatewayModels)
 	);
+	const manualCompact = new ManagedManualCompact(pi, contextWindows);
 	const dependencies: CompactionDependencies = {
-		loadConfig,
 		remoteCompact: executeRemoteV2Compaction,
 		nativeFallback: runNativeFallbackCompaction,
 		contextWindows,
 		...overrides,
+		manualCompact,
+		loadConfig: () => manualCompact.snapshot ?? loadConfig(),
 		piContextHookPatch: overrides.piContextHookPatch ?? piContextHookPatch,
 	};
 	let tools!: ReturnType<typeof registerContextManagementTools>;
@@ -1193,6 +1203,8 @@ export default function registerCompactionExtension(
 			assertConfigValid(resolved, "context", "compatibility");
 			return { active: await isContextRuntimeActive(ctx, resolved.config.compaction), gatewayModels: resolved.gatewayModelKeys };
 		},
+		undefined,
+		manualCompact,
 	);
 	const remoteContextActive: RemoteContextActive = isContextRuntimeActive;
 	const syncTools = async (
@@ -1233,6 +1245,7 @@ export default function registerCompactionExtension(
 	pi.on("session_start", async (_event, ctx) => {
 		const resolved = contextOperation(dependencies.loadConfig, ctx);
 		const syncOutcome = await syncTools(ctx, ctx.model, { notifyWindowFailure: true }, resolved);
+		await manualCompact.recover(ctx);
 		const active = syncOutcome.eligible && syncOutcome.toolsSynced && syncOutcome.windowInitialized;
 		const { source } = resolved;
 		const warnings = resolved.issues.map((issue) => `${issue.path}: ${issue.code}`);
@@ -1291,10 +1304,17 @@ export default function registerCompactionExtension(
 		}
 	});
 
-	pi.on("context", (event, ctx) => handleContext(event, ctx, pi, dependencies.loadConfig, contextWindows, remoteContextActive));
+	pi.on("context_with_system", (event, ctx) => {
+		manualCompact.guardRequest(ctx);
+		return handleContext(event, ctx, pi, dependencies.loadConfig, contextWindows, remoteContextActive);
+	});
 	pi.on("session_before_compact", (event, ctx) => handleSessionBeforeCompact(event, ctx, dependencies, remoteContextActive));
 	pi.on("session_compact", (event, _ctx) => contextWindows.recordCompaction(event.compactionEntry.details));
-	pi.on("session_shutdown", () => {
+	pi.on("session_compact_failed", async (event, ctx) => {
+		if (event.reason === "manual" && !manualCompact.isMaintenance) await manualCompact.compactFailed(ctx);
+	});
+	pi.on("session_shutdown", async (_event, ctx) => {
+		await manualCompact.shutdown(ctx);
 		contextWindowReady = false;
 		contextWindows.reset();
 		tools.reset();
@@ -1302,9 +1322,11 @@ export default function registerCompactionExtension(
 	pi.on("agent_settled", async (_event, ctx) => {
 		// Idle: no retry, compaction, or queued continuation is left running, so this is the
 		// only safe place to spend a model call on the user's behalf.
-		await handleWindowBulk(ctx, contextWindows, dependencies.loadConfig, "turn-end");
+		if (await manualCompact.settled(ctx)) return;
+		await handleWindowBulk(ctx, contextWindows, dependencies.loadConfig, "turn-end", undefined, () => manualCompact.beginMaintenance());
 	});
 	pi.on("model_select", async (event, ctx) => {
+		manualCompact.modelSelected(event.model, ctx);
 		// Switching into a covered model mid-session must open the window
 		// lifecycle immediately: without an identity the request rewrite skips
 		// window metadata, the backend never ingests those turns, and the first
@@ -1314,12 +1336,24 @@ export default function registerCompactionExtension(
 		await syncTools(ctx, event.model, { notifyWindowFailure: true }, resolved);
 		// The switch itself is the moment the durable transcript changes consumer, and the
 		// session is idle here, so the close-out must happen now rather than mid-turn.
-		await handleWindowBulk(ctx, contextWindows, dependencies.loadConfig, "model-switch", resolved);
+		if (!manualCompact.busy) await handleWindowBulk(ctx, contextWindows, dependencies.loadConfig, "model-switch", resolved, () => manualCompact.beginMaintenance());
 	});
 	pi.on("before_agent_start", async (_event, ctx) => {
 		await syncTools(ctx, ctx.model, { notifyWindowFailure: true });
 	});
-	pi.on("before_provider_request", (event, ctx) => handleBeforeProviderRequest(event, ctx, dependencies.loadConfig, contextWindows, remoteContextActive));
+	pi.on("thinking_level_select", (event, ctx) => manualCompact.thinkingSelected(event.level, ctx));
+	pi.on("message_start", (event) => manualCompact.messageStarted(event.message));
+	pi.on("turn_end", (_event, ctx) => manualCompact.turnEnded(ctx));
+	pi.on("tool_call", (event) => manualCompact.guardTool(event.toolName));
+	pi.on("session_tree", async (_event, ctx) => {
+		contextWindows.synchronize(ctx);
+		await manualCompact.recover(ctx);
+		await syncTools(ctx);
+	});
+	pi.on("before_provider_request", (event, ctx) => {
+		manualCompact.guardRequest(ctx);
+		return handleBeforeProviderRequest(event, ctx, dependencies.loadConfig, contextWindows, remoteContextActive);
+	});
 	pi.on("before_provider_headers", async (event, ctx) => {
 		const resolved = contextOperation(dependencies.loadConfig, ctx);
 		requireContextPolicy(resolved, ctx);

package/src/payload-rewrite.ts

@@ -1,12 +1,7 @@
-import { sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
+import { buildSessionProjection, sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type { Api, Model } from "@earendil-works/pi-ai";
-import type {
-	BranchSummaryEntry,
-	CustomMessageEntry,
-	SessionEntry,
-	SessionMessageEntry,
-} from "@earendil-works/pi-coding-agent";
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
 import type { ResponsesCompatibleRequestPayload } from "./runtime";
 import { hasVerifiedCompactionInputProvenance } from "./compaction-projection";
 import { rewritePayloadWithDeferredToolCarryover } from "./deferred-tool-carryover";
@@ -40,7 +35,8 @@ export type NativeReplayPayloadRewriteFailureReason =
 	| "unexpected-compaction-after-boundary"
 	| "compaction-summary-not-found"
 	| "retained-context-mismatch"
-	| "unverified-compaction-input";
+	| "unverified-compaction-input"
+	| "checkpoint-context-edited";
 
 export type NativeReplayPayloadRewriteFailure = {
 	ok: false;
@@ -200,46 +196,6 @@ function areEquivalentValues(left: unknown, right: unknown): boolean {
 	return false;
 }
 
-function toBranchSummaryMessage(entry: BranchSummaryEntry): AgentMessage {
-	return {
-		role: "branchSummary",
-		summary: entry.summary,
-		fromId: entry.fromId,
-		timestamp: new Date(entry.timestamp).getTime(),
-	} as AgentMessage;
-}
-
-function toCustomMessage(entry: CustomMessageEntry): AgentMessage {
-	return {
-		role: "custom",
-		customType: entry.customType,
-		content: entry.content,
-		display: entry.display,
-		details: entry.details,
-		timestamp: new Date(entry.timestamp).getTime(),
-	} as AgentMessage;
-}
-
-function toSessionMessage(entry: SessionMessageEntry): AgentMessage {
-	return entry.message;
-}
-
-function toReplayAgentMessage(entry: SessionEntry): AgentMessage | undefined {
-	if (entry.type === "message") {
-		return toSessionMessage(entry);
-	}
-
-	if (entry.type === "custom_message") {
-		return toCustomMessage(entry);
-	}
-
-	if (entry.type === "branch_summary") {
-		return toBranchSummaryMessage(entry);
-	}
-
-	return undefined;
-}
-
 function extractUserItemText(item: Record<string, unknown>): unknown {
 	const { content } = item;
 	if (typeof content === "string") {
@@ -273,23 +229,29 @@ function findCompactionSummaryIndex(input: readonly unknown[], summaryMarker: st
 }
 
 function collectReplayMessages(entries: readonly SessionEntry[]): AgentMessage[] {
-	const messages: AgentMessage[] = [];
-
-	for (const entry of entries) {
-		const message = toReplayAgentMessage(entry);
-		if (message) {
-			messages.push(message);
-		}
-	}
+	return buildSessionProjection([...entries]).messages;
+}
 
-	return messages;
+/** An opaque checkpoint cannot be selectively edited after it was produced. */
+export function hasInvalidatedCompactionContext(
+	entries: readonly SessionEntry[],
+	compactionEntryId: string,
+): boolean {
+	const boundary = findCompactionBoundaryIndex(entries, compactionEntryId);
+	if (boundary === undefined) return false;
+	const coveredIds = new Set(entries.slice(0, boundary).map((entry) => entry.id));
+	return entries.slice(boundary + 1).some((entry) =>
+		entry.type === "context_edit" && coveredIds.has(entry.targetId),
+	);
 }
 
-function findEntryIndexByIdBeforeBoundary(
+function findKeptEntryIndex(
 	entries: readonly SessionEntry[],
 	entryId: string,
 	boundaryIndex: number,
 ): number | undefined {
+	// Pi 0.87 uses the compaction itself as the retained boundary for retain-none.
+	if (entries[boundaryIndex]?.id === entryId) return boundaryIndex;
 	const index = entries.findIndex((entry, candidateIndex) => candidateIndex < boundaryIndex && entry.id === entryId);
 	return index >= 0 ? index : undefined;
 }
@@ -319,7 +281,7 @@ export function collectLiveTailMessages(entries: readonly SessionEntry[]): Agent
 }
 
 /**
- * Remote V2 covers the complete pre-compaction context. Pi 0.85.1 also retains
+ * Remote V2 covers the complete pre-compaction context. Pi also retains
  * recent messages, so remove those verified copies before provider conversion
  * (where IDs/fields may change across models). Persisted session entries are
  * untouched. Preserve transient additions and all post-compaction messages.
@@ -335,7 +297,10 @@ export function removeNativeCompactionRetainedMessages(args: {
 	if (!hasVerifiedCompactionInputProvenance(args.compactionEntry.details, args.expectedInputProvenance)) {
 		return { ok: false, reason: "unverified-compaction-input" };
 	}
-	const firstKept = findEntryIndexByIdBeforeBoundary(args.branchEntries, args.compactionEntry.firstKeptEntryId, boundary);
+	if (hasInvalidatedCompactionContext(args.branchEntries, args.compactionEntry.id)) {
+		return { ok: false, reason: "checkpoint-context-edited" };
+	}
+	const firstKept = findKeptEntryIndex(args.branchEntries, args.compactionEntry.firstKeptEntryId, boundary);
 	if (firstKept === undefined) return { ok: false, reason: "first-kept-entry-not-found" };
 	const summaryMessage = sessionEntryToContextMessages(args.compactionEntry).find(
 		(message) => message.role === "compactionSummary",
@@ -344,9 +309,10 @@ export function removeNativeCompactionRetainedMessages(args: {
 	const summary = structuredClone(summaryMessage);
 	const summaryIndex = args.messages.findIndex((message) => areEquivalentValues(message, summary));
 	if (summaryIndex < 0) return { ok: false, reason: "compaction-summary-not-found" };
-	const retained = args.branchEntries
-		.slice(firstKept, boundary)
-		.flatMap(sessionEntryToContextMessages)
+	const retainedIds = new Set(args.branchEntries.slice(firstKept, boundary).map((entry) => entry.id));
+	const retained = buildSessionProjection([...args.branchEntries]).entries
+		.filter((entry) => retainedIds.has(entry.sourceEntry.id))
+		.flatMap((entry) => entry.messages)
 		.map((message) => structuredClone(message));
 	// Custom messages are optional context-hook entries: a hook may filter or
 	// rewrite them before provider serialization. An exact custom copy is still
@@ -418,7 +384,11 @@ function buildNativeReplaySegmentsInternal<TApi extends Api>(args: {
 		};
 	}
 
-	const firstKeptEntryIndex = findEntryIndexByIdBeforeBoundary(
+	if (hasInvalidatedCompactionContext(args.branchEntries, args.compactionEntry.id)) {
+		return { ok: false, reason: "checkpoint-context-edited" };
+	}
+
+	const firstKeptEntryIndex = findKeptEntryIndex(
 		args.branchEntries,
 		args.compactionEntry.firstKeptEntryId,
 		boundaryIndex,

package/src/pi-context-hook.ts

@@ -1,116 +1,117 @@
-import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import { ExtensionRunner, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-
-/** Context property added by the toolkit's host patch. */
-export const PI_CONTEXT_PROJECTOR_FIELD = "projectContextForCompaction" as const;
-const PI_CONTEXT_PROJECTION_REPORTER_FIELD = "__piOpenAiToolkitReportContextProjectionFailure" as const;
-const PATCH_MARKER_FIELD = "__piOpenAiToolkitContextHookPatch" as const;
-
-type ProjectionState = {
-	failure?: string;
-};
-
-const activeProjectionByRunner = new WeakMap<ExtensionRunner, ProjectionState>();
-
-type PatchedExtensionContext = ExtensionContext & {
-	[PI_CONTEXT_PROJECTOR_FIELD]?: PiContextHookProjector;
-	[PI_CONTEXT_PROJECTION_REPORTER_FIELD]?: (reason: string) => void;
-};
-
-type MarkedCreateContext = typeof ExtensionRunner.prototype.createContext & {
-	[PATCH_MARKER_FIELD]?: true;
-};
-
-/** The ordered context-hook chain, applied to a cloned compaction context. */
-export type PiContextHookProjector = (
-	messages: readonly AgentMessage[],
-) => Promise<readonly AgentMessage[]>;
-
-export type PiContextHookPatchResult =
-	| { ok: true; installed: boolean; reason?: "already-installed" }
-	| { ok: false; reason: "emit-context-unavailable" | "create-context-unavailable" };
-
-/**
- * Add a narrow projection method to every ExtensionContext created by Pi.
- *
- * Pi 0.85.1 already has the ordered `ExtensionRunner.emitContext()` method,
- * but the event-level ExtensionContext does not expose the runner. The patch
- * bridges only the method needed by Remote V2; it does not expose the runner
- * or alter Pi's scheduler.
- */
-export function installPiContextHookPatch(): PiContextHookPatchResult {
-	const prototype = ExtensionRunner.prototype;
-	if (typeof prototype.emitContext !== "function") {
-		return { ok: false, reason: "emit-context-unavailable" };
-	}
-
-	const original = prototype.createContext;
-	if (typeof original !== "function") {
-		return { ok: false, reason: "create-context-unavailable" };
-	}
-
-	const markedOriginal = original as MarkedCreateContext;
-	if (markedOriginal[PATCH_MARKER_FIELD] === true) {
-		return { ok: true, installed: false, reason: "already-installed" };
-	}
-
-	const patched = function patchedCreateContext(this: ExtensionRunner): ExtensionContext {
-		const context = original.call(this) as PatchedExtensionContext;
-		if (!(PI_CONTEXT_PROJECTOR_FIELD in context)) {
-			Object.defineProperty(context, PI_CONTEXT_PROJECTOR_FIELD, {
-				configurable: false,
-				enumerable: false,
-				writable: false,
-				value: async (messages: readonly AgentMessage[]) => {
-					const state: ProjectionState = {};
-					activeProjectionByRunner.set(this, state);
-					try {
-						const projected = await this.emitContext([...messages]);
-						if (state.failure) {
-							throw new Error(`context projection failed: ${state.failure}`);
-						}
-						return projected;
-					} finally {
-						if (activeProjectionByRunner.get(this) === state) {
-							activeProjectionByRunner.delete(this);
-						}
-					}
-				},
-			});
-		}
-		if (!(PI_CONTEXT_PROJECTION_REPORTER_FIELD in context)) {
-			Object.defineProperty(context, PI_CONTEXT_PROJECTION_REPORTER_FIELD, {
-				configurable: false,
-				enumerable: false,
-				writable: false,
-				value: (reason: string) => {
-					const state = activeProjectionByRunner.get(this);
-					if (state) state.failure = reason;
-				},
-			});
-		}
-		return context;
-	};
-
-	Object.defineProperty(patched, PATCH_MARKER_FIELD, {
-		configurable: false,
-		enumerable: false,
-		writable: false,
-		value: true,
-	});
-	prototype.createContext = patched;
-	return { ok: true, installed: true };
-}
-
-/** Return the patched projection method, if this Pi process supports it. */
-export function getPiContextHookProjector(
-	ctx: ExtensionContext,
-): PiContextHookProjector | undefined {
-	const candidate = (ctx as PatchedExtensionContext)[PI_CONTEXT_PROJECTOR_FIELD];
-	return typeof candidate === "function" ? candidate : undefined;
-}
-
-/** Preserve fail-closed context-hook errors across Pi's emitContext boundary. */
-export function reportPiContextHookFailure(ctx: ExtensionContext, reason: string): void {
-	(ctx as PatchedExtensionContext)[PI_CONTEXT_PROJECTION_REPORTER_FIELD]?.(reason);
-}
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { ExtensionRunner, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+/** Context property added by the toolkit's host patch. */
+export const PI_CONTEXT_PROJECTOR_FIELD = "projectContextForCompaction" as const;
+const PI_CONTEXT_PROJECTION_REPORTER_FIELD = "__piOpenAiToolkitReportContextProjectionFailure" as const;
+const PATCH_MARKER_FIELD = "__piOpenAiToolkitContextHookPatch" as const;
+
+type ProjectionState = {
+	failure?: string;
+};
+
+const activeProjectionByRunner = new WeakMap<ExtensionRunner, ProjectionState>();
+
+type PatchedExtensionContext = ExtensionContext & {
+	[PI_CONTEXT_PROJECTOR_FIELD]?: PiContextHookProjector;
+	[PI_CONTEXT_PROJECTION_REPORTER_FIELD]?: (reason: string) => void;
+};
+
+type MarkedCreateContext = typeof ExtensionRunner.prototype.createContext & {
+	[PATCH_MARKER_FIELD]?: true;
+};
+
+/** The ordered context-hook chain, applied to a cloned compaction context. */
+export type PiContextHookProjector = (
+	messages: readonly AgentMessage[],
+) => Promise<readonly AgentMessage[]>;
+
+export type PiContextHookPatchResult =
+	| { ok: true; installed: boolean; reason?: "already-installed" }
+	| { ok: false; reason: "emit-context-unavailable" | "create-context-unavailable" };
+
+/**
+ * Add a narrow projection method to every ExtensionContext created by Pi.
+ *
+ * Pi 0.87's ordered `ExtensionRunner.emitContext()` runs both `context` and
+ * `context_with_system` phases,
+ * but the event-level ExtensionContext does not expose the runner. The patch
+ * bridges only the method needed by Remote V2; it does not expose the runner
+ * or alter Pi's scheduler.
+ */
+export function installPiContextHookPatch(): PiContextHookPatchResult {
+	const prototype = ExtensionRunner.prototype;
+	if (typeof prototype.emitContext !== "function") {
+		return { ok: false, reason: "emit-context-unavailable" };
+	}
+
+	const original = prototype.createContext;
+	if (typeof original !== "function") {
+		return { ok: false, reason: "create-context-unavailable" };
+	}
+
+	const markedOriginal = original as MarkedCreateContext;
+	if (markedOriginal[PATCH_MARKER_FIELD] === true) {
+		return { ok: true, installed: false, reason: "already-installed" };
+	}
+
+	const patched = function patchedCreateContext(this: ExtensionRunner): ExtensionContext {
+		const context = original.call(this) as PatchedExtensionContext;
+		if (!(PI_CONTEXT_PROJECTOR_FIELD in context)) {
+			Object.defineProperty(context, PI_CONTEXT_PROJECTOR_FIELD, {
+				configurable: false,
+				enumerable: false,
+				writable: false,
+				value: async (messages: readonly AgentMessage[]) => {
+					const state: ProjectionState = {};
+					activeProjectionByRunner.set(this, state);
+					try {
+						const projected = await this.emitContext([...messages]);
+						if (state.failure) {
+							throw new Error(`context projection failed: ${state.failure}`);
+						}
+						return projected;
+					} finally {
+						if (activeProjectionByRunner.get(this) === state) {
+							activeProjectionByRunner.delete(this);
+						}
+					}
+				},
+			});
+		}
+		if (!(PI_CONTEXT_PROJECTION_REPORTER_FIELD in context)) {
+			Object.defineProperty(context, PI_CONTEXT_PROJECTION_REPORTER_FIELD, {
+				configurable: false,
+				enumerable: false,
+				writable: false,
+				value: (reason: string) => {
+					const state = activeProjectionByRunner.get(this);
+					if (state) state.failure = reason;
+				},
+			});
+		}
+		return context;
+	};
+
+	Object.defineProperty(patched, PATCH_MARKER_FIELD, {
+		configurable: false,
+		enumerable: false,
+		writable: false,
+		value: true,
+	});
+	prototype.createContext = patched;
+	return { ok: true, installed: true };
+}
+
+/** Return the patched projection method, if this Pi process supports it. */
+export function getPiContextHookProjector(
+	ctx: ExtensionContext,
+): PiContextHookProjector | undefined {
+	const candidate = (ctx as PatchedExtensionContext)[PI_CONTEXT_PROJECTOR_FIELD];
+	return typeof candidate === "function" ? candidate : undefined;
+}
+
+/** Preserve fail-closed context-hook errors across Pi's emitContext boundary. */
+export function reportPiContextHookFailure(ctx: ExtensionContext, reason: string): void {
+	(ctx as PatchedExtensionContext)[PI_CONTEXT_PROJECTION_REPORTER_FIELD]?.(reason);
+}