pi-openai-toolkit 0.14.9 → 0.14.10

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.10",
   "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

@@ -94,7 +94,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 +117,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 +167,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.",

package/src/extension-runtime.ts

@@ -301,6 +301,7 @@ async function runResponsesNativeCompact(
 				...serializeMessagesToResponsesInput(
 					compactor.currentModel,
 					[...projection.messages.slice(summaryIndex + 1)],
+					{ firstSystemMessageIsUpdate: true },
 				),
 			];
 			request = {

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";