pi-openai-toolkit 0.14.9 → 0.14.11

package/docs/internals.md

@@ -52,6 +52,7 @@ sequenceDiagram
   Toolkit->>Toolkit: verify successful notes write in this window
   Toolkit-->>Model: checkpoint receipt with the successful note path
   Toolkit-->>Pi: window marker appended, previous window trim scheduled
+  Note over Model: Context switch is complete; read the receipt once, then resume the active task
   Model->>Backend: next request with the new x-codex-window-id
   Pi->>Toolkit: session_before_compact
   Toolkit-->>Pi: no-summary boundary consuming the scheduled trim
@@ -62,6 +63,7 @@ State invariants the lifecycle code must keep honest:
 - The checkpoint gate verifies a successful `notes` `append_to_file` or `write_file` against the persisted session branch after the latest window boundary, so it survives restarts and forks. A response with `ok: false` or `success: false` is not successful, even when HTTP returns 200.
 - The gate uses the live session/branch identity from `ctx.sessionManager`; cached manager identity must not hide a valid current-window pair, and old or foreign-session evidence must remain rejected.
 - Every rollover carries the most recent successful checkpoint path in its handoff message. The optional `thread_hint` is supplemental; a hint failure must not erase the local receipt.
+- A successful rollover closes the pre-rollover checkpoint phase. The first turn in the new window reads the receipt once and resumes the active user task; it must not immediately create another checkpoint or call `new_context` as part of that handoff. A later checkpoint is only for a later rollover.
 - `new_context` has no force escape hatch: a persisted successful notes checkpoint in the current window is always required before rollover. The model must wait for the notes result to be persisted before retrying.
 - After a marker is accepted for sending, the manager keeps a session/window-anchored pending guard until that exact target marker is persisted or the session changes. A duplicate `new_context` during this persistence gap returns `started: false` and sends no second marker; projected/in-memory messages do not retire the guard.
 - Budget checks are skipped until the current window has produced its own assistant usage. Acting on the previous window's usage anchor would burn the once-per-window reminder on a false alarm.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-openai-toolkit",
-  "version": "0.14.9",
+  "version": "0.14.11",
   "private": false,
   "type": "module",
   "engines": {
@@ -32,20 +32,7 @@
     "codex",
     "responses"
   ],
-  "pi": {
-    "extensions": [
-      "./extensions/compaction.ts",
-      "./extensions/web-search.ts",
-      "./extensions/image-generation.ts",
-      "./extensions/auto-mode.ts",
-      "./extensions/codex-astra.ts"
-    ]
-  },
   "files": [
-    "extensions/compaction.ts",
-    "extensions/web-search.ts",
-    "extensions/image-generation.ts",
-    "extensions/auto-mode.ts",
     "src/compact-client.ts",
     "src/compaction-projection.ts",
     "src/pi-context-hook.ts",
@@ -81,7 +68,6 @@
     "src/auto-mode/reviewer.ts",
     "src/auto-mode/classifier.ts",
     "src/auto-mode/types.ts",
-    "extensions/codex-astra.ts",
     "src/codex-astra/effort-planner.ts",
     "src/codex-astra/extension.ts",
     "src/model-scope.ts",
@@ -120,10 +106,10 @@
     "@earendil-works/pi-tui": ">=0.85.1"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "0.85.1",
-    "@earendil-works/pi-ai": "0.85.1",
-    "@earendil-works/pi-coding-agent": "0.85.1",
-    "@earendil-works/pi-tui": "0.85.1",
+    "@earendil-works/pi-agent-core": "0.86.0",
+    "@earendil-works/pi-ai": "0.86.0",
+    "@earendil-works/pi-coding-agent": "0.86.0",
+    "@earendil-works/pi-tui": "0.86.0",
     "@types/node": "24.12.4",
     "bun": "1.2.23",
     "typescript": "5.9.3"

package/src/auto-mode/reviewer.ts

@@ -1,4 +1,12 @@
-import type { Api, AssistantMessage, Context, Message, Model, Tool } from "@earendil-works/pi-ai";
+import type {
+	Api,
+	AssistantMessage,
+	Context,
+	Message,
+	Model,
+	Tool,
+	ToolCall,
+} from "@earendil-works/pi-ai";
 import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
 import { parseModelSpec } from "../runtime";
 import { backfillVerdictFields, buildReviewPrompt, reviewerSystemPrompt } from "./prompt";
@@ -93,11 +101,13 @@ function firstTextBlock(message: AssistantMessage): string {
 		.trim();
 }
 
-function toolCallBlocks(message: AssistantMessage) {
-	return message.content.filter(
-		(block): block is { type: "toolCall"; id: string; name: string; arguments: Record<string, unknown> } =>
-			block.type === "toolCall",
-	);
+/**
+ * Pi 0.85 typed tool-call arguments as `Record<string, any>` and Pi 0.86 tightened
+ * them to the public `JsonObject`. Narrow with Pi's exported `ToolCall` instead of a
+ * handwritten shape so the guard tracks whichever contract the installed Pi declares.
+ */
+function toolCallBlocks(message: AssistantMessage): ToolCall[] {
+	return message.content.filter((block): block is ToolCall => block.type === "toolCall");
 }
 
 type CompletionAttempt = {

package/src/context-management/messages.ts

@@ -35,7 +35,7 @@ export const CONTEXT_WINDOW_COMPACTION_SUMMARY =
 	"[Pi Codex context-window boundary; no conversation summary was generated.]";
 
 const CONTEXT_WINDOW_GUIDANCE = `<context_window_guidance>
-Checkpoint the active request, known history IDs, decisions, progress, learnings and next steps in notes before new_context, and wait for that notes result to be persisted; only a persisted successful result in the current window unlocks the rollover, and no summary carries over. If new_context reports that a rollover is already scheduled, do not call it again in the same window. After rollover, read the checkpoint receipt note first when present; use a thread hint only as supplemental guidance. Use history only for a missing detail.
+Before calling new_context, checkpoint the active request, known history IDs, decisions, progress, learnings and next steps in notes, and wait for that result to be persisted; only a persisted successful result in the current window unlocks the rollover. If new_context reports that a rollover is already scheduled, do not call it again in the same window. When this message includes a completed context-switch handoff, follow that post-rollover section first instead of restarting the pre-rollover checkpoint steps. A thread hint is supplemental and must not replace the local checkpoint receipt. No conversation summary carries over, and history is only for missing details.
 </context_window_guidance>`;
 
 export function renderContextWindowMessage(
@@ -51,8 +51,11 @@ export function renderContextWindowMessage(
 	];
 	if (identity.previousWindowId) lines.push(`Previous context window id: ${identity.previousWindowId}`);
 	if (checkpoint) {
+		lines.push("Context switch completed. This is the first turn in the new context window.");
 		lines.push("Checkpoint successfully written:");
 		lines.push(`  Read this note before doing anything else with notes action "read_file": ${JSON.stringify(checkpoint.path)}`);
+		lines.push("After reading the checkpoint receipt, resume the active user task.");
+		lines.push("Do not immediately create another checkpoint or call new_context as part of this handoff. Only prepare a new checkpoint when a later context rollover is actually needed.");
 	}
 	if (threadHint) lines.push(threadHint);
 	lines.push("</context_window>");

package/src/context-management/tools.ts

@@ -12,13 +12,25 @@ import type { HistoryAction, NotesAction } from "./types";
 
 const EMPTY_PARAMETERS = Type.Object({}, { additionalProperties: false });
 
-function arrayEquals(a: readonly string[] | undefined, b: readonly string[] | undefined): boolean {
-	if (a === b) return true;
-	if (!a || !b || a.length !== b.length) return false;
-	for (let i = 0; i < a.length; i++) {
-		if (a[i] !== b[i]) return false;
-	}
-	return true;
+type PublishedTool = {
+	name: string;
+	description: string;
+	parameters: unknown;
+	promptGuidelines?: string[];
+};
+
+/**
+ * Pi's ToolInfo wrapper is new, but its definition fields retain the objects
+ * registered by the extension. Keep identity checks for those fields: an exact
+ * foreign clone under the same name is still not ownership of our tool.
+ */
+function isOurTool(
+	actual: PublishedTool,
+	expected: { description: string; parameters: unknown; promptGuidelines?: string[] },
+): boolean {
+	return actual.description === expected.description
+		&& actual.parameters === expected.parameters
+		&& actual.promptGuidelines === expected.promptGuidelines;
 }
 const HISTORY_ACTIONS = Object.keys(HISTORY_ENDPOINTS) as [HistoryAction, ...HistoryAction[]];
 const NOTES_ACTIONS = Object.keys(NOTES_ENDPOINTS) as [NotesAction, ...NotesAction[]];
@@ -94,7 +106,8 @@ export function createContextManagementTools(
 		parameters: NEW_CONTEXT_PARAMETERS,
 		promptSnippet: "Start a new remote Codex context window without summarizing history.",
 		promptGuidelines: [
-			"Checkpoint active work in notes before calling new_context; no conversation summary carries over. Only a persisted successful notes append/write in the current window unlocks the rollover.",
+			"Before this new_context call, checkpoint active work in notes; only a persisted successful notes append/write in the current window unlocks this rollover, and no conversation summary carries over.",
+			"A successful new_context completes one context switch. In the next window, read the checkpoint receipt first when present, then resume the active user task; do not immediately create another checkpoint or call new_context as part of that handoff.",
 			"Wait for the notes tool result before calling new_context; an in-flight or failed write is not a checkpoint. If new_context reports that a rollover is already scheduled, do not call it again in the same window.",
 		],
 		executionMode: "sequential",
@@ -116,7 +129,12 @@ export function createContextManagementTools(
 				trimPreviousWindow: true,
 			});
 			return {
-				content: [{ type: "text", text: started ? "A new context window will start without summarizing conversation history." : "A new context window is already scheduled." }],
+				content: [{
+					type: "text",
+					text: started
+						? "Context switch scheduled successfully. In the next context window, read the checkpoint receipt first when present, then resume the active user task; do not immediately create another checkpoint or call new_context."
+						: "A new context window is already scheduled.",
+				}],
 				details: { started },
 			};
 		},
@@ -161,6 +179,7 @@ export function createContextManagementTools(
 		promptSnippet: "Read and checkpoint remote Codex notes across context windows.",
 		promptGuidelines: [
 			"Before calling new_context, checkpoint the current turn's active work (unfinished tasks, decisions, open questions, references) into notes with append_to_file or write_file so it survives the window change; wait for that result to be persisted before calling new_context.",
+			"After a successful new_context handoff, read the checkpoint receipt first when present and resume the active user task; do not immediately create another checkpoint or call new_context unless a later rollover is actually needed.",
 			"When a large task spans multiple context windows, keep a running note per line of work and read it at the start of each new window; append new state instead of replacing it unless the note is stale.",
 			"Prefer read_file or search_contents for looking things up; reserve write_file for explicit rewrite/clear and append_to_file for incremental state.",
 			"Keep note text concise and self-contained: it may be read later without the rest of the conversation, so include identifiers and verbatim key decisions, not hearsay summaries.",
@@ -175,6 +194,13 @@ export function createContextManagementTools(
 	return { newContext, getContextRemaining, history, notes };
 }
 
+export type ContextToolRegistrationState = "verified" | "conflict" | "unverified";
+
+export type ContextToolSyncResult = {
+	synced: boolean;
+	registrationState: ContextToolRegistrationState;
+};
+
 export class ContextManagementToolController {
 	private readonly registeredNames = new Set<string>();
 	private readonly definitions = new Map<string, {
@@ -183,8 +209,7 @@ export class ContextManagementToolController {
 		promptGuidelines?: string[];
 	}>();
 	private registered = false;
-	private registrationChecked = false;
-	private registrationValid = false;
+	private verifiedOnce = false;
 
 	constructor(private readonly pi: ExtensionAPI) {}
 
@@ -198,12 +223,16 @@ export class ContextManagementToolController {
 		// those are bound only after extension loading completes.
 		try {
 			for (const definition of definitions) api.registerTool(definition);
+			this.registered = true;
 		} catch {
+			// Pi rejects a registration whose name is already owned elsewhere.
+			this.registered = false;
 			return false;
 		}
 
 		this.registeredNames.clear();
 		this.definitions.clear();
+		this.verifiedOnce = false;
 		for (const definition of definitions) {
 			this.registeredNames.add(definition.name);
 			this.definitions.set(definition.name, {
@@ -212,43 +241,58 @@ export class ContextManagementToolController {
 				promptGuidelines: definition.promptGuidelines,
 			});
 		}
-		this.registered = true;
-		this.registrationChecked = false;
-		this.registrationValid = false;
+		// A successful call only proves the hand-off; it does not prove the runtime
+		// published the definitions. `checkRegistration()` reads that from Pi.
 		return true;
 	}
 
-	private verifyRegistration(): boolean {
-		if (!this.registered) return false;
-		if (this.registrationChecked) return this.registrationValid;
-		this.registrationChecked = true;
+	/**
+	 * Read registration state until the runtime confirms publication.
+	 *
+	 * Pi 0.86 can reject action methods while a session replacement is still
+	 * binding, and can publish the registry after `session_start` ran. Negative
+	 * reads remain retryable; only a successful verification is cached for this
+	 * controller instance. A Pi reload creates a new controller.
+	 */
+	checkRegistration(): ContextToolRegistrationState {
+		if (!this.registered) return "conflict";
+		// A confirmed publication is kept: the expensive part was never the read, it
+		// was trusting a failed one. Only negative verdicts are recomputed each time.
+		if (this.verifiedOnce) return "verified";
+		let available: PublishedTool[];
 		try {
-			const api = this.pi as ExtensionAPI & { getAllTools?: () => Array<{
-				name: string;
-				description: string;
-				parameters: unknown;
-				promptGuidelines?: string[];
-			}> };
-			if (typeof api.getAllTools !== "function") return false;
-			const available = new Map(api.getAllTools().map((tool) => [tool.name, tool]));
-			this.registrationValid = [...this.registeredNames].every((name) => {
-				const actual = available.get(name);
-				const expected = this.definitions.get(name);
-				return actual !== undefined && expected !== undefined &&
-					actual.description === expected.description &&
-					actual.parameters === expected.parameters &&
-					actual.promptGuidelines === expected.promptGuidelines;
-			});
+			const api = this.pi as ExtensionAPI & { getAllTools?: () => PublishedTool[] };
+			if (typeof api.getAllTools !== "function") return "conflict";
+			available = api.getAllTools();
 		} catch {
-			this.registrationValid = false;
+			// Stale or unbound runtime: retry on the next sync.
+			return "unverified";
+		}
+		const byName = new Map(available.map((tool) => [tool.name, tool]));
+		let missing = false;
+		let conflict = false;
+		for (const name of this.registeredNames) {
+			const actual = byName.get(name);
+			const expected = this.definitions.get(name);
+			if (actual === undefined || expected === undefined) {
+				missing = true;
+				continue;
+			}
+			if (!isOurTool(actual, expected)) conflict = true;
 		}
-		return this.registrationValid;
+		if (conflict) return "conflict";
+		if (missing) return "unverified";
+		this.verifiedOnce = true;
+		return "verified";
 	}
 
-	sync(active: boolean): boolean {
-		if (!this.verifyRegistration()) return false;
+	sync(active: boolean): ContextToolSyncResult {
+		const registrationState = this.checkRegistration();
+		if (registrationState !== "verified") return { synced: false, registrationState };
 		const api = this.pi as ExtensionAPI & { getActiveTools?: () => string[]; setActiveTools?: (names: string[]) => void };
-		if (typeof api.getActiveTools !== "function" || typeof api.setActiveTools !== "function") return false;
+		if (typeof api.getActiveTools !== "function" || typeof api.setActiveTools !== "function") {
+			return { synced: false, registrationState };
+		}
 		try {
 			const current = api.getActiveTools();
 			// Pi may activate a newly registered tool before the first sync. Once
@@ -258,16 +302,17 @@ export class ContextManagementToolController {
 				? [...current, ...[...this.registeredNames].filter((name) => !current.includes(name))]
 				: current.filter((name) => !this.registeredNames.has(name));
 			if (next.length !== current.length) api.setActiveTools(next);
-			return true;
+			return { synced: true, registrationState };
 		} catch {
-			return false;
+			return { synced: false, registrationState };
 		}
 	}
 
 	reset(): void {
 		this.sync(false);
 	}
-	get isRegistered(): boolean { return this.registrationValid; }
+	get isRegistered(): boolean { return this.checkRegistration() === "verified"; }
+	get registrationState(): ContextToolRegistrationState { return this.checkRegistration(); }
 }
 
 export function registerContextManagementTools(

package/src/extension-runtime.ts

@@ -17,7 +17,10 @@ import {
 import { routeContextNamespaceToolMessage } from "./context-management/namespace-tools";
 import { loadHistoryNotesThreadHint } from "./context-management/history-notes";
 import { CodexContextWindowManager } from "./context-management/window-manager";
-import { registerContextManagementTools } from "./context-management/tools";
+import {
+	registerContextManagementTools,
+	type ContextToolRegistrationState,
+} from "./context-management/tools";
 import { writeDebugArtifact, writeReplayFailureArtifact } from "./debug";
 import {
 	COMPACTION_CHECKPOINT_PROVENANCE_UNAVAILABLE,
@@ -88,6 +91,13 @@ type RemoteContextActive = (
 	model?: ExtensionContext["model"],
 ) => Promise<boolean>;
 
+type ContextToolSyncOutcome = {
+	eligible: boolean;
+	toolsSynced: boolean;
+	registrationState: ContextToolRegistrationState;
+	windowInitialized: boolean;
+};
+
 type ResponsesCompactOutcome =
 	| { outcome: "success"; compaction: CompactionResult<NativeCompactionDetails> }
 	| { outcome: "aborted" }
@@ -301,6 +311,7 @@ async function runResponsesNativeCompact(
 				...serializeMessagesToResponsesInput(
 					compactor.currentModel,
 					[...projection.messages.slice(summaryIndex + 1)],
+					{ firstSystemMessageIsUpdate: true },
 				),
 			];
 			request = {
@@ -1014,28 +1025,60 @@ export default function registerCompactionExtension(
 		piContextHookPatch: overrides.piContextHookPatch ?? piContextHookPatch,
 	};
 	let tools!: ReturnType<typeof registerContextManagementTools>;
+	let contextWindowReady = false;
+	const isContextRuntimeActive = async (
+		ctx: ExtensionContext,
+		config: CompactionConfig,
+		model = ctx.model,
+	): Promise<boolean> =>
+		contextWindowReady && tools.isRegistered && await isRemoteContextActive(ctx, config, model);
 	tools = registerContextManagementTools(
 		pi,
 		contextWindows,
 		async (ctx) => {
 			const config = dependencies.loadConfig().config.compaction;
-			return tools.isRegistered && await isRemoteContextActive(ctx, config);
+			return isContextRuntimeActive(ctx, config);
 		},
 		() => dependencies.loadConfig().config.compaction.gatewayContextModels,
 	);
-	const remoteContextActive: RemoteContextActive = async (ctx, config, model = ctx.model) =>
-		tools.isRegistered && await isRemoteContextActive(ctx, config, model);
-	const syncTools = async (ctx: ExtensionContext, model = ctx.model): Promise<boolean> => {
+	const remoteContextActive: RemoteContextActive = isContextRuntimeActive;
+	const syncTools = async (
+		ctx: ExtensionContext,
+		model = ctx.model,
+		options: { notifyWindowFailure?: boolean } = {},
+	): Promise<ContextToolSyncOutcome> => {
+		// Until this call proves otherwise, do not let a previous session/window
+		// identity make a failed activation look usable.
+		contextWindowReady = false;
 		const config = dependencies.loadConfig().config.compaction;
-		const active = await isRemoteContextActive(ctx, config, model);
-		// sync() reports whether the tool-set update succeeded; an inactive model
-		// syncs fine and returns true. The activation decision must use `active`
-		// itself, or non-covered models would receive a window boundary.
-		const synced = tools.sync(active);
-		return active && synced;
+		const eligible = await isRemoteContextActive(ctx, config, model);
+		const toolSync = tools.sync(eligible);
+		const outcome: ContextToolSyncOutcome = {
+			eligible,
+			toolsSynced: toolSync.synced,
+			registrationState: toolSync.registrationState,
+			windowInitialized: false,
+		};
+		if (!eligible || !toolSync.synced) return outcome;
+		// Activation can succeed after `session_start` missed it, because Pi 0.86 may
+		// reject the registration read while a session replacement is still binding.
+		// The window lifecycle has to open on that later activation too, or requests
+		// carry no window metadata and the backend never ingests the turns.
+		try {
+			contextWindows.ensureInitialized(pi, ctx, true);
+			contextWindowReady = true;
+			return { ...outcome, windowInitialized: true };
+		} catch {
+			// Do not leave tools exposed while the request path has no valid window
+			// identity. The next lifecycle hook may retry once Pi is usable again.
+			tools.sync(false);
+			if (options.notifyWindowFailure) notifyRemoteContextFailure(ctx, "malformed-window-state");
+			return outcome;
+		}
 	};
 	pi.on("session_start", async (_event, ctx) => {
-		const active = await syncTools(ctx);
+		const syncOutcome = await syncTools(ctx, ctx.model, { notifyWindowFailure: true });
+		const active = syncOutcome.eligible && syncOutcome.toolsSynced && syncOutcome.windowInitialized;
 		const { config: toolkitConfig, source, warnings } = dependencies.loadConfig();
 		const config = toolkitConfig.compaction;
 		if (!config.enabled) return;
@@ -1043,16 +1086,16 @@ export default function registerCompactionExtension(
 		let activationReason: string | undefined;
 		// Only models the built-in Remote Context coverage targets may activate or
 		// warn; everything else silently runs Pi's normal compaction path.
-		if (config.contextManagement === "remote" && isCodexContextModel(ctx.model, config)) {
-			if (active) {
-				try {
-					contextWindows.ensureInitialized(pi, ctx, true);
-				} catch {
-					notifyRemoteContextFailure(ctx, "malformed-window-state");
-				}
-			} else if (!tools.isRegistered) {
+		if (config.contextManagement === "remote" && isCodexContextModel(ctx.model, config) && !active) {
+			if (syncOutcome.registrationState === "conflict") {
 				activationReason = "tool-name-conflict";
 				notifyRemoteContextFailure(ctx, activationReason);
+			} else if (syncOutcome.registrationState === "unverified" || !syncOutcome.toolsSynced) {
+				// Transient: the runtime has not published or accepted our tools yet. A
+				// later before_agent_start re-verifies, so do not report provider failure.
+				activationReason = "tool-registration-pending";
+			} else if (syncOutcome.eligible && !syncOutcome.windowInitialized) {
+				activationReason = "malformed-window-state";
 			} else {
 				const remoteResolution = await resolveCodexContextProvider(ctx, ctx.model, config.gatewayContextModels);
 				activationReason = remoteResolution.ok ? "codex-context-unavailable" : remoteResolution.reason;
@@ -1098,25 +1141,20 @@ export default function registerCompactionExtension(
 	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", () => {
+		contextWindowReady = false;
 		contextWindows.reset();
 		tools.reset();
 	});
 	pi.on("model_select", async (event, ctx) => {
-		const active = await syncTools(ctx, event.model);
 		// 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
 		// new_context would trim pre-switch history that no history can recover.
-		// ensureInitialized is idempotent when a window already exists.
-		if (!active) return;
-		try {
-			contextWindows.ensureInitialized(pi, ctx, true);
-		} catch {
-			notifyRemoteContextFailure(ctx, "malformed-window-state");
-		}
+		// syncTools() activates and initializes the window when the model is covered.
+		await syncTools(ctx, event.model, { notifyWindowFailure: true });
 	});
 	pi.on("before_agent_start", async (_event, ctx) => {
-		await syncTools(ctx);
+		await syncTools(ctx, ctx.model, { notifyWindowFailure: true });
 	});
 	pi.on("before_provider_request", (event, ctx) => handleBeforeProviderRequest(event, ctx, dependencies.loadConfig, contextWindows, remoteContextActive));
 	pi.on("before_provider_headers", async (event, ctx) => {

package/src/payload-rewrite.ts

@@ -337,7 +337,11 @@ export function removeNativeCompactionRetainedMessages(args: {
 	}
 	const firstKept = findEntryIndexByIdBeforeBoundary(args.branchEntries, args.compactionEntry.firstKeptEntryId, boundary);
 	if (firstKept === undefined) return { ok: false, reason: "first-kept-entry-not-found" };
-	const summary = structuredClone(sessionEntryToContextMessages(args.compactionEntry)[0]);
+	const summaryMessage = sessionEntryToContextMessages(args.compactionEntry).find(
+		(message) => message.role === "compactionSummary",
+	);
+	if (!summaryMessage) return { ok: false, reason: "compaction-summary-not-found" };
+	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
@@ -349,7 +353,13 @@ export function removeNativeCompactionRetainedMessages(args: {
 	// removed when present, while a missing or rewritten copy is left alone.
 	// Required user/assistant/tool messages keep the ordered, fail-closed
 	// matching contract.
-	const requiredRetained = retained.filter((message) => message.role !== "custom");
+	// Pi 0.86 promotes transcript system messages to the leading prompt when it
+	// rebuilds context after compaction. They can therefore appear before the
+	// compaction summary even when their session entry lies inside the retained
+	// span; keep them in place instead of treating that relocation as a mismatch.
+	const requiredRetained = retained.filter(
+		(message) => message.role !== "custom" && (message.role as string) !== "system",
+	);
 	const optionalRetained = retained.filter((message) => message.role === "custom");
 	const removed = new Set<number>();
 	let cursor = summaryIndex + 1;
@@ -388,7 +398,9 @@ export function serializeLiveTailToResponsesInput<TApi extends Api>(args: {
 	model: Model<TApi>;
 	entries: readonly SessionEntry[];
 }): ResponsesInputItem[] {
-	return serializeMessagesToResponsesInput(args.model, collectReplayMessages(args.entries));
+	return serializeMessagesToResponsesInput(args.model, collectReplayMessages(args.entries), {
+		firstSystemMessageIsUpdate: true,
+	});
 }
 
 function buildNativeReplaySegmentsInternal<TApi extends Api>(args: {

package/src/serializer.ts

@@ -89,6 +89,21 @@ export type ResponsesFunctionCallOutputItem = {
 
 export type ResponsesReasoningItem = Record<string, unknown>;
 
+/**
+ * Pi 0.86 adds `SystemMessage` to the public `Message` union; 0.85.1 has no system
+ * variant and does not export that type name. Use the public shape when the installed
+ * Pi declares it and a structural fallback for the fields this serializer consumes
+ * otherwise, so one source file type-checks against both supported versions.
+ */
+type ResponsesSystemMessage = Extract<Message, { role: "system" }> extends never
+	? {
+			role: "system";
+			content: string | TextContent[];
+			sections?: Record<string, string | null>;
+			timestamp: number;
+		}
+	: Extract<Message, { role: "system" }>;
+
 export type ResponsesInputItem =
 	| ResponsesInputMessageItem
 	| ResponsesAssistantOutputItem
@@ -106,6 +121,8 @@ export type NativeCompactionRequestBody = CompactionRequestExtras & {
 export type SerializeResponsesMessagesOptions = {
 	instructions?: string;
 	includeInstructionsInInput?: boolean;
+	/** Treat a system message at the start of a sliced post-compaction tail as an update. */
+	firstSystemMessageIsUpdate?: boolean;
 };
 
 export type ResponsesParityReport = {
@@ -126,6 +143,13 @@ function sanitizeSurrogates(text: string): string {
 	return text.replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, "");
 }
 
+function instructionRole<TApi extends Api>(model: Model<TApi>): "developer" | "system" {
+	// Pi's public Model compat union is broader than the OpenAI Responses compat
+	// shape, while the runtime field is shared by both supported Pi versions.
+	const compat = model.compat as { supportsDeveloperRole?: boolean } | undefined;
+	return model.reasoning && compat?.supportsDeveloperRole !== false ? "developer" : "system";
+}
+
 export function collectCompactionWindowMessages(preparation: CompactionPreparation): AgentMessage[] {
 	return [...preparation.messagesToSummarize, ...preparation.turnPrefixMessages];
 }
@@ -159,19 +183,38 @@ export function serializeMessagesToResponsesInput<TApi extends Api>(
 	messages: AgentMessage[],
 	options: SerializeResponsesMessagesOptions = {},
 ): ResponsesInputItem[] {
-	const llmMessages = convertToLlm(messages);
-	const transformedMessages = transformMessagesForResponses(llmMessages);
+	return serializeLlmMessagesToResponsesInput(model, convertToLlm(messages), options);
+}
+
+/**
+ * Serialize Pi's normalized LLM message union without running `convertToLlm` again.
+ * This keeps the system-message boundary directly testable while preserving the public
+ * AgentMessage-facing entry point above.
+ */
+export function serializeLlmMessagesToResponsesInput<TApi extends Api>(
+	model: Model<TApi>,
+	messages: Message[],
+	options: SerializeResponsesMessagesOptions = {},
+): ResponsesInputItem[] {
+	const transformedMessages = transformMessagesForResponses(messages);
 	const input: ResponsesInputItem[] = [];
 
 	if (options.includeInstructionsInInput && options.instructions) {
 		input.push({
-			role: model.reasoning ? "developer" : "system",
+			role: instructionRole(model),
 			content: sanitizeSurrogates(options.instructions),
 		});
 	}
 
 	let messageIndex = 0;
+	let sourceIndex = 0;
 	for (const message of transformedMessages) {
+		// Pi 0.85's Message union has no system member, so compare through the
+		// public role string while keeping the 0.86 discriminant runtime-compatible.
+		const isFirstMessage = sourceIndex++ === 0;
+		const isLeadingSystemMessage =
+			!options.firstSystemMessageIsUpdate && isFirstMessage && (message.role as string) === "system";
+
 		if (message.role === "user") {
 			const item = serializeUserMessage(message, model);
 			if (item) {
@@ -190,8 +233,21 @@ export function serializeMessagesToResponsesInput<TApi extends Api>(
 			continue;
 		}
 
-		input.push(serializeToolResultMessage(message, model));
-		messageIndex++;
+		if (message.role === "toolResult") {
+			input.push(serializeToolResultMessage(message, model));
+			messageIndex++;
+			continue;
+		}
+
+		// In Pi 0.85.1 this branch narrows to `never`; in Pi 0.86 it is a SystemMessage.
+		// Handle it explicitly instead of letting a new message variant become tool output.
+		const systemItem = serializeSystemMessage(message, model, isLeadingSystemMessage);
+		if (systemItem) {
+			input.push(systemItem);
+		}
+		if (!isLeadingSystemMessage) {
+			messageIndex++;
+		}
 	}
 
 	return input;
@@ -446,6 +502,72 @@ function normalizeUserContent(content: UserMessage["content"]): Array<TextConten
 	return typeof content === "string" ? [{ type: "text", text: content }] : content;
 }
 
+/**
+ * Serialize one normalized Pi system message as a Responses input message.
+ *
+ * The role follows the same reasoning-model convention as `instructions`: reasoning
+ * models use `developer`, everything else keeps `system`. Leading messages include
+ * their complete section state; later messages use Pi's update framing so section
+ * additions/removals are not mistaken for a new complete prompt. An empty system
+ * message produces no item, matching Pi.
+ */
+function serializeSystemMessage<TApi extends Api>(
+	message: ResponsesSystemMessage,
+	model: Model<TApi>,
+	isLeadingSystemMessage: boolean,
+): ResponsesInputMessageItem | undefined {
+	const text = sanitizeSurrogates(
+		isLeadingSystemMessage ? getSystemMessageText(message) : renderSystemMessageUpdate(message),
+	);
+	if (text.length === 0) {
+		return undefined;
+	}
+
+	return {
+		role: instructionRole(model),
+		content: text,
+	};
+}
+
+/** Mirrors Pi's public getSystemMessageText() without importing a 0.86-only helper. */
+function getSystemMessageText(message: ResponsesSystemMessage): string {
+	const parts = [contentText(message.content)];
+	for (const text of Object.values(message.sections ?? {})) {
+		if (text !== null) {
+			parts.push(text);
+		}
+	}
+	return parts.filter((part) => part.length > 0).join("\n\n");
+}
+
+/** Mirrors Pi's public renderSystemMessageUpdate() for later transcript updates. */
+function renderSystemMessageUpdate(message: ResponsesSystemMessage): string {
+	const parts: string[] = [];
+	const text = contentText(message.content);
+	if (text.length > 0) {
+		parts.push(text);
+	}
+	for (const [name, value] of Object.entries(message.sections ?? {})) {
+		parts.push(
+			value === null
+				? `Removed system prompt section "${name}".`
+				: `Updated system prompt section "${name}":\n\n${value}`,
+		);
+	}
+	return parts.join("\n\n");
+}
+
+function contentText(content: ResponsesSystemMessage["content"]): string {
+	if (typeof content === "string") {
+		return content;
+	}
+
+	return content
+		.filter((item): item is TextContent => item.type === "text")
+		.map((item) => item.text)
+		.join("\n");
+}
+
 function parseReasoningItem(block: ThinkingContent): ResponsesReasoningItem | undefined {
 	if (!block.thinkingSignature) {
 		return undefined;

package/tsconfig.check.json

@@ -12,10 +12,6 @@
     "typeRoots": ["./node_modules/@types"]
   },
   "include": [
-    "extensions/compaction.ts",
-    "extensions/web-search.ts",
-    "extensions/image-generation.ts",
-    "extensions/auto-mode.ts",
     "src/compact-client.ts",
     "src/compaction-projection.ts",
     "src/pi-context-hook.ts",

package/extensions/auto-mode.ts

@@ -1 +0,0 @@
-export { default } from "../src/auto-mode/extension.ts";

package/extensions/codex-astra.ts

@@ -1 +0,0 @@
-export { default } from "../src/codex-astra/extension.ts";

package/extensions/compaction.ts

@@ -1 +0,0 @@
-export { default } from "../src/extension-runtime.ts";

package/extensions/image-generation.ts

@@ -1 +0,0 @@
-export { default } from "../src/image-generation/extension.ts";

package/extensions/web-search.ts

@@ -1 +0,0 @@
-export { default } from "../src/web-search/extension.ts";