pi-openai-toolkit 0.14.7 → 0.14.9

package/src/codex-astra/extension.ts

@@ -1,122 +1,122 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { ASTRA_MODEL_ID } from "../types";
-import { CODEX_CLIENT_VERSION } from "../responses-headers";
-import {
-	getEffortControlState,
-	planStableEffort,
-	type EffortControlState,
-	type PlannableInputItem,
-} from "./effort-planner";
-
-type AstraPayload = {
-	model: string;
-	input: PlannableInputItem[];
-	reasoning: { effort: string; [key: string]: unknown };
-	[key: string]: unknown;
-};
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return !!value && typeof value === "object" && !Array.isArray(value);
-}
-
-/**
- * Recognize the live Codex Responses request body: model + wire input array
- * + a request-level string effort. Anything else (titles, embeddings, or a
- * shape we do not understand) is left untouched.
- */
-function parseAstraPayload(payload: unknown): AstraPayload | undefined {
-	if (!isRecord(payload)) return undefined;
-	if (typeof payload.model !== "string") return undefined;
-	if (!Array.isArray(payload.input)) return undefined;
-	const reasoning = payload.reasoning;
-	if (!isRecord(reasoning) || typeof reasoning.effort !== "string") return undefined;
-	if (reasoning.effort.length === 0 || reasoning.effort === "none") return undefined;
-	if (!payload.input.every((item) => isRecord(item))) return undefined;
-	return payload as unknown as AstraPayload;
-}
-
-function isCompactionShaped(payload: AstraPayload): boolean {
-	// A `compaction_trigger` history belongs to a compact endpoint request,
-	// which rejects `configuration_update` items. Our compaction clients use
-	// direct fetch and never reach this hook; this guard covers any future
-	// provider-routed compaction.
-	const last = payload.input[payload.input.length - 1];
-	return !!last && isRecord(last) && last.type === "compaction_trigger";
-}
-
-function getSessionId(ctx: { sessionManager: { getSessionId(): string } }): string | undefined {
-	try {
-		return ctx.sessionManager.getSessionId();
-	} catch {
-		return undefined;
-	}
-}
-
-export function registerCodexAstraExtension(pi: ExtensionAPI): void {
-	const states = new Map<string, EffortControlState>();
-
-	// Switching or forking a session rebuilds the runtime and re-fires
-	// session_start; clearing there covers every replacement path.
-	pi.on("session_start", () => {
-		states.clear();
-	});
-
-	pi.on("before_provider_request", (event, ctx) => {
-		try {
-			// Silent activation by design: the Astra compatibility layer exists only
-			// to keep `gpt-6-astra` working through the Codex backend gate, so it
-			// keys off the bare model id instead of an operator allowlist.
-			const model = ctx.model;
-			// Both Responses wire families carry the same reasoning.effort prefix
-			// problem, and upstream OMP plans on both providers.
-			if (!model || (model.api !== "openai-codex-responses" && model.api !== "openai-responses")) {
-				return undefined;
-			}
-			if (model.id !== ASTRA_MODEL_ID) return undefined;
-
-			const payload = parseAstraPayload(event.payload);
-			// The payload must belong to the model the eligibility check just
-			// passed; a mismatch means this request is not ours to plan.
-			if (!payload || payload.model !== model.id) return undefined;
-			if (isCompactionShaped(payload)) return undefined;
-
-			const sessionId = getSessionId(ctx);
-			const state = getEffortControlState(
-				states,
-				`${model.baseUrl ?? ""}\u0000${model.id}\u0000${sessionId ?? "no-session"}`,
-			);
-
-			// Idempotence: never plan on top of items a previous pass injected.
-			const history = payload.input.filter((item) => item.type !== "configuration_update");
-			const { input, result } = planStableEffort(state, history, payload.reasoning.effort);
-			if (result.effort === payload.reasoning.effort && result.spliced === 0) return undefined;
-
-			return {
-				...payload,
-				input,
-				reasoning: { ...payload.reasoning, effort: result.effort },
-			};
-		} catch {
-			// A planner failure must never break the provider request path.
-			return undefined;
-		}
-	});
-
-	pi.on("before_provider_headers", (event, ctx) => {
-		try {
-			const model = ctx.model;
-			if (!model || model.api !== "openai-codex-responses") return;
-			// Live requests need the same backend version gate as our synthetic
-			// ones: an old or missing `version` never reaches gated SKUs.
-			if (!event.headers.version) {
-				event.headers.version = CODEX_CLIENT_VERSION;
-			}
-		} catch {
-			// Header injection is best-effort.
-		}
-	});
-}
-
-export default function codexAstraExtension(pi: ExtensionAPI): void {
-	registerCodexAstraExtension(pi);
-}
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { ASTRA_MODEL_ID } from "../types";
+import { CODEX_CLIENT_VERSION } from "../responses-headers";
+import {
+	getEffortControlState,
+	planStableEffort,
+	type EffortControlState,
+	type PlannableInputItem,
+} from "./effort-planner";
+
+type AstraPayload = {
+	model: string;
+	input: PlannableInputItem[];
+	reasoning: { effort: string; [key: string]: unknown };
+	[key: string]: unknown;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Recognize the live Codex Responses request body: model + wire input array
+ * + a request-level string effort. Anything else (titles, embeddings, or a
+ * shape we do not understand) is left untouched.
+ */
+function parseAstraPayload(payload: unknown): AstraPayload | undefined {
+	if (!isRecord(payload)) return undefined;
+	if (typeof payload.model !== "string") return undefined;
+	if (!Array.isArray(payload.input)) return undefined;
+	const reasoning = payload.reasoning;
+	if (!isRecord(reasoning) || typeof reasoning.effort !== "string") return undefined;
+	if (reasoning.effort.length === 0 || reasoning.effort === "none") return undefined;
+	if (!payload.input.every((item) => isRecord(item))) return undefined;
+	return payload as unknown as AstraPayload;
+}
+
+function isCompactionShaped(payload: AstraPayload): boolean {
+	// A `compaction_trigger` history belongs to a compact endpoint request,
+	// which rejects `configuration_update` items. Our compaction clients use
+	// direct fetch and never reach this hook; this guard covers any future
+	// provider-routed compaction.
+	const last = payload.input[payload.input.length - 1];
+	return !!last && isRecord(last) && last.type === "compaction_trigger";
+}
+
+function getSessionId(ctx: { sessionManager: { getSessionId(): string } }): string | undefined {
+	try {
+		return ctx.sessionManager.getSessionId();
+	} catch {
+		return undefined;
+	}
+}
+
+export function registerCodexAstraExtension(pi: ExtensionAPI): void {
+	const states = new Map<string, EffortControlState>();
+
+	// Switching or forking a session rebuilds the runtime and re-fires
+	// session_start; clearing there covers every replacement path.
+	pi.on("session_start", () => {
+		states.clear();
+	});
+
+	pi.on("before_provider_request", (event, ctx) => {
+		try {
+			// Silent activation by design: the Astra compatibility layer exists only
+			// to keep `gpt-6-astra` working through the Codex backend gate, so it
+			// keys off the bare model id instead of an operator allowlist.
+			const model = ctx.model;
+			// Both Responses wire families carry the same reasoning.effort prefix
+			// problem, and upstream OMP plans on both providers.
+			if (!model || (model.api !== "openai-codex-responses" && model.api !== "openai-responses")) {
+				return undefined;
+			}
+			if (model.id !== ASTRA_MODEL_ID) return undefined;
+
+			const payload = parseAstraPayload(event.payload);
+			// The payload must belong to the model the eligibility check just
+			// passed; a mismatch means this request is not ours to plan.
+			if (!payload || payload.model !== model.id) return undefined;
+			if (isCompactionShaped(payload)) return undefined;
+
+			const sessionId = getSessionId(ctx);
+			const state = getEffortControlState(
+				states,
+				`${model.baseUrl ?? ""}\u0000${model.id}\u0000${sessionId ?? "no-session"}`,
+			);
+
+			// Idempotence: never plan on top of items a previous pass injected.
+			const history = payload.input.filter((item) => item.type !== "configuration_update");
+			const { input, result } = planStableEffort(state, history, payload.reasoning.effort);
+			if (result.effort === payload.reasoning.effort && result.spliced === 0) return undefined;
+
+			return {
+				...payload,
+				input,
+				reasoning: { ...payload.reasoning, effort: result.effort },
+			};
+		} catch {
+			// A planner failure must never break the provider request path.
+			return undefined;
+		}
+	});
+
+	pi.on("before_provider_headers", (event, ctx) => {
+		try {
+			const model = ctx.model;
+			if (!model || model.api !== "openai-codex-responses") return;
+			// Live requests need the same backend version gate as our synthetic
+			// ones: an old or missing `version` never reaches gated SKUs.
+			if (!event.headers.version) {
+				event.headers.version = CODEX_CLIENT_VERSION;
+			}
+		} catch {
+			// Header injection is best-effort.
+		}
+	});
+}
+
+export default function codexAstraExtension(pi: ExtensionAPI): void {
+	registerCodexAstraExtension(pi);
+}

package/src/compaction-projection.ts

@@ -0,0 +1,31 @@
+import type {
+	NativeCompactionDetails,
+	NativeCompactionInputProvenance,
+} from "./types";
+
+/** The configured Pi context-hook projector is unavailable or failed. */
+export const COMPACTION_PROJECTION_UNAVAILABLE = "no-supported-projection-seam" as const;
+/** The current session context could not be read before projection. */
+export const COMPACTION_SESSION_CONTEXT_UNAVAILABLE = "session-context-unavailable" as const;
+/** A projected recursive context did not contain the current compaction summary. */
+export const COMPACTION_PROJECTED_CONTEXT_UNAVAILABLE = "projected-compaction-context-unavailable" as const;
+/** The latest opaque checkpoint was created with no or a different input marker. */
+export const COMPACTION_CHECKPOINT_PROVENANCE_UNAVAILABLE = "unverified-compaction-checkpoint" as const;
+
+export type UnprojectedCompactionReason =
+	| typeof COMPACTION_PROJECTION_UNAVAILABLE
+	| typeof COMPACTION_SESSION_CONTEXT_UNAVAILABLE
+	| typeof COMPACTION_CHECKPOINT_PROVENANCE_UNAVAILABLE
+	| typeof COMPACTION_PROJECTED_CONTEXT_UNAVAILABLE;
+
+/**
+ * A Remote V2 checkpoint is safe for the current replay chain only when its
+ * marker matches the configured input source. Structural persistence validation
+ * intentionally remains more permissive for old session files.
+ */
+export function hasVerifiedCompactionInputProvenance(
+	details: Pick<NativeCompactionDetails, "inputProvenance"> | undefined,
+	expected: NativeCompactionInputProvenance,
+): boolean {
+	return details?.inputProvenance === expected;
+}

package/src/config.ts

@@ -31,10 +31,12 @@ import {
 	type CompactionConfig,
 	type ContextManagementMode,
 	type ImageGenerationConfig,
+	type RemoteV2ContextSource,
 	type LoadedToolkitConfig,
 	type NativeFallbackConfig,
 	type ToolkitConfig,
 	type WebSearchConfig,
+	type WebSearchRoute,
 } from "./types";
 import { MAX_IMAGE_MODEL_ID_CHARS } from "./image-generation/types";
 
@@ -47,6 +49,7 @@ const COMPACTION_FIELDS = new Set([
 	"contextManagement",
 	"allowCompactionContinuityBreak",
 	"remoteCompactModel",
+	"remoteV2ContextSource",
 	"nativeFallback",
 	"responsesApis",
 	"gatewayContextModels",
@@ -59,7 +62,7 @@ const COMPACTION_FIELDS = new Set([
 	"artifactRoot",
 ]);
 const NATIVE_FALLBACK_FIELDS = new Set(["enabled", "model", "thinkingLevel"]);
-const WEB_SEARCH_FIELDS = new Set(["enabled", "models"]);
+const WEB_SEARCH_FIELDS = new Set(["enabled", "models", "defaultRoute", "routes"]);
 const IMAGE_GENERATION_FIELDS = new Set(["enabled", "models"]);
 const AUTO_MODE_FIELDS = new Set([
 	"enabled",
@@ -148,6 +151,20 @@ function toContextManagementMode(
 	return undefined;
 }
 
+function toRemoteV2ContextSource(
+	value: unknown,
+	fieldPath: string,
+	warnings: string[],
+): RemoteV2ContextSource | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value === "string") {
+		const normalized = value.trim();
+		if (normalized === "pi-context-hook" || normalized === "legacy") return normalized;
+	}
+	warnings.push(`Ignoring ${fieldPath}: expected one of pi-context-hook, legacy.`);
+	return undefined;
+}
+
 function toModelSpec(value: unknown, fieldPath: string, warnings: string[]): string | null | undefined {
 	if (value === undefined) return undefined;
 	if (value === null) return null;
@@ -231,6 +248,53 @@ function toImageGenerationModels(value: unknown, fieldPath: string, warnings: st
 	return models;
 }
 
+function toWebSearchRoute(
+	value: unknown,
+	fieldPath: string,
+	warnings: string[],
+): WebSearchRoute | undefined {
+	if (value === undefined) return undefined;
+	if (value === "local" || value === "hosted" || value === "standalone-alpha") {
+		return value;
+	}
+	warnings.push(`Ignoring ${fieldPath}: expected one of local, hosted, standalone-alpha.`);
+	return undefined;
+}
+
+function isExactWebSearchModelKey(value: string): boolean {
+	const trimmed = value.trim();
+	const separatorIndex = trimmed.indexOf("/");
+	if (separatorIndex <= 0 || separatorIndex >= trimmed.length - 1) return false;
+	if (/[\s*?\[\]{}]/.test(trimmed)) return false;
+	const provider = trimmed.slice(0, separatorIndex);
+	const modelId = trimmed.slice(separatorIndex + 1);
+	return provider.length > 0 && modelId.length > 0;
+}
+
+function toWebSearchRoutes(
+	value: unknown,
+	fieldPath: string,
+	warnings: string[],
+): Record<string, WebSearchRoute> | undefined {
+	if (value === undefined) return undefined;
+	if (!isRecord(value)) {
+		warnings.push(`Ignoring ${fieldPath}: expected a JSON object.`);
+		return undefined;
+	}
+
+	const routes: Record<string, WebSearchRoute> = {};
+	for (const [rawKey, rawRoute] of Object.entries(value)) {
+		const key = rawKey.trim();
+		if (!isExactWebSearchModelKey(key)) {
+			warnings.push(`Ignoring ${fieldPath}.${rawKey}: expected an exact "provider/model-id" key.`);
+			continue;
+		}
+		const route = toWebSearchRoute(rawRoute, `${fieldPath}.${rawKey}`, warnings);
+		if (route !== undefined) routes[key] = route;
+	}
+	return routes;
+}
+
 function toAutoModeGate(value: unknown, fieldPath: string, warnings: string[]): AutoModeGate | undefined {
 	if (value === undefined) return undefined;
 	if (value === "side-effect" || value === "all") return value;
@@ -264,6 +328,12 @@ function cloneDefaults(): ToolkitConfig {
 		webSearch: {
 			...DEFAULT_WEB_SEARCH_CONFIG,
 			models: [...DEFAULT_WEB_SEARCH_CONFIG.models],
+			...(DEFAULT_WEB_SEARCH_CONFIG.defaultRoute
+				? { defaultRoute: DEFAULT_WEB_SEARCH_CONFIG.defaultRoute }
+				: {}),
+			...(DEFAULT_WEB_SEARCH_CONFIG.routes
+				? { routes: { ...DEFAULT_WEB_SEARCH_CONFIG.routes } }
+				: {}),
 		},
 		imageGeneration: {
 			...DEFAULT_IMAGE_GENERATION_CONFIG,
@@ -347,6 +417,10 @@ function applyCompactionConfig(
 		resolved.remoteCompactModel = remoteCompactModelSpec === null ? undefined : remoteCompactModelSpec;
 	}
 
+	resolved.remoteV2ContextSource =
+		toRemoteV2ContextSource(raw.remoteV2ContextSource, "compaction.remoteV2ContextSource", warnings) ??
+		resolved.remoteV2ContextSource;
+
 	if (raw.nativeFallback !== undefined) {
 		if (isRecord(raw.nativeFallback)) {
 			applyNativeFallbackConfig(raw.nativeFallback, resolved.nativeFallback, warnings);
@@ -393,6 +467,31 @@ function applyWebSearchConfig(
 	if (models !== undefined) {
 		resolved.models = models;
 	}
+
+	const defaultRoute = toWebSearchRoute(raw.defaultRoute, "webSearch.defaultRoute", warnings);
+	if (defaultRoute !== undefined) {
+		resolved.defaultRoute = defaultRoute;
+	}
+
+	const routes = toWebSearchRoutes(raw.routes, "webSearch.routes", warnings);
+	if (routes !== undefined) {
+		resolved.routes = routes;
+	}
+
+	if (defaultRoute !== undefined && resolved.models.length > 0) {
+		warnings.push(
+			"webSearch.defaultRoute overrides legacy webSearch.models for models without an exact webSearch.routes entry.",
+		);
+	}
+	if (routes !== undefined) {
+		for (const key of Object.keys(routes)) {
+			if (resolved.models.includes(key)) {
+				warnings.push(
+					`webSearch.routes.${key} overrides the legacy webSearch.models entry for the same exact model.`,
+				);
+			}
+		}
+	}
 }
 
 function applyImageGenerationConfig(

package/src/context-management/messages.ts

@@ -1,112 +1,112 @@
-import { randomUUID } from "node:crypto";
-import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import {
-	CODEX_CONTEXT_WINDOW_MESSAGE_TYPE,
-	CONTEXT_MANAGEMENT_PROTOCOL,
-	CONTEXT_WINDOW_COMPACTION_STRATEGY,
-	CONTEXT_WINDOW_FALLBACK_BUFFER,
-	CONTEXT_WINDOW_REMINDER_THRESHOLD,
-	type CodexContextManagementMessageDetails,
-	type ContextManagementMessageKind,
-	type ContextWindowCompactionDetails,
-	type ContextWindowIdentity,
-	type NotesCheckpointReceipt,
-	isCodexContextManagementMessageDetails,
-	isContextWindowCompactionDetails,
-} from "./types";
-
-export {
-	CODEX_CONTEXT_WINDOW_MESSAGE_TYPE,
-	CONTEXT_WINDOW_COMPACTION_STRATEGY,
-	CONTEXT_WINDOW_FALLBACK_BUFFER,
-	CONTEXT_WINDOW_REMINDER_THRESHOLD,
-	isCodexContextManagementMessageDetails,
-	isContextWindowCompactionDetails,
-};
-export type {
-	CodexContextManagementMessageDetails,
-	ContextManagementMessageKind,
-	ContextWindowCompactionDetails,
-	ContextWindowIdentity,
-};
-
-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; no summary carries over. 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.
-</context_window_guidance>`;
-
-export function renderContextWindowMessage(
-	identity: ContextWindowIdentity,
-	threadHint?: string,
-	checkpoint?: NotesCheckpointReceipt,
-): string {
-	const lines = [
-		"<context_window>",
-		"Agent name: /root",
-		`First context window id: ${identity.firstWindowId}`,
-		`Current context window id: ${identity.currentWindowId}`,
-	];
-	if (identity.previousWindowId) lines.push(`Previous context window id: ${identity.previousWindowId}`);
-	if (checkpoint) {
-		lines.push("Checkpoint successfully written:");
-		lines.push(`  Read this note before doing anything else with notes action "read_file": ${JSON.stringify(checkpoint.path)}`);
-	}
-	if (threadHint) lines.push(threadHint);
-	lines.push("</context_window>");
-	return `${CONTEXT_WINDOW_GUIDANCE}\n\n${lines.join("\n")}`;
-}
-
-export function renderContextWindowReminder(remainingTokens: number): string {
-	return `<context_window_reminder>
-Only ${Math.max(0, Math.floor(remainingTokens))} context tokens remain. Checkpoint the active request, state and known history IDs in notes, then call new_context; no conversation summary carries over.
-</context_window_reminder>`;
-}
-
-export const CONTEXT_WINDOW_FALLBACK_MESSAGE = `<context_window_reminder>
-Context exhausted. Do not continue or answer. Make exactly one notes write or append call that checkpoints the active request, state and known history IDs, then call new_context. Use no other tools before rollover.
-</context_window_reminder>`;
-
-export function isContextWindowBoundary(
-	message: AgentMessage,
-): message is Extract<AgentMessage, { role: "custom" }> & {
-	details: CodexContextManagementMessageDetails;
-} {
-	return (
-		message.role === "custom" &&
-		message.customType === CODEX_CONTEXT_WINDOW_MESSAGE_TYPE &&
-		isCodexContextManagementMessageDetails(message.details) &&
-		message.details.contextManagement.kind === "window"
-	);
-}
-
-export function sendContextWindowMessage(
-	pi: ExtensionAPI,
-	content: string,
-	kind: ContextManagementMessageKind,
-	identity: ContextWindowIdentity,
-	options: { triggerTurn: boolean; sessionId?: string },
-	trimPreviousWindow = false,
-): void {
-	const details: CodexContextManagementMessageDetails = {
-		protocol: CONTEXT_MANAGEMENT_PROTOCOL,
-		id: randomUUID(),
-		...(options.sessionId ? { sessionId: options.sessionId } : {}),
-		contextManagement: {
-			protocol: CONTEXT_MANAGEMENT_PROTOCOL,
-			kind,
-			...identity,
-			...(trimPreviousWindow ? { trimPreviousWindow: true as const } : {}),
-		},
-	};
-	pi.sendMessage({
-		customType: CODEX_CONTEXT_WINDOW_MESSAGE_TYPE,
-		content,
-		display: true,
-		details,
-	}, options.triggerTurn
-		? { deliverAs: "steer", triggerTurn: true }
-		: { triggerTurn: false });
-}
+import { randomUUID } from "node:crypto";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	CODEX_CONTEXT_WINDOW_MESSAGE_TYPE,
+	CONTEXT_MANAGEMENT_PROTOCOL,
+	CONTEXT_WINDOW_COMPACTION_STRATEGY,
+	CONTEXT_WINDOW_FALLBACK_BUFFER,
+	CONTEXT_WINDOW_REMINDER_THRESHOLD,
+	type CodexContextManagementMessageDetails,
+	type ContextManagementMessageKind,
+	type ContextWindowCompactionDetails,
+	type ContextWindowIdentity,
+	type NotesCheckpointReceipt,
+	isCodexContextManagementMessageDetails,
+	isContextWindowCompactionDetails,
+} from "./types";
+
+export {
+	CODEX_CONTEXT_WINDOW_MESSAGE_TYPE,
+	CONTEXT_WINDOW_COMPACTION_STRATEGY,
+	CONTEXT_WINDOW_FALLBACK_BUFFER,
+	CONTEXT_WINDOW_REMINDER_THRESHOLD,
+	isCodexContextManagementMessageDetails,
+	isContextWindowCompactionDetails,
+};
+export type {
+	CodexContextManagementMessageDetails,
+	ContextManagementMessageKind,
+	ContextWindowCompactionDetails,
+	ContextWindowIdentity,
+};
+
+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.
+</context_window_guidance>`;
+
+export function renderContextWindowMessage(
+	identity: ContextWindowIdentity,
+	threadHint?: string,
+	checkpoint?: NotesCheckpointReceipt,
+): string {
+	const lines = [
+		"<context_window>",
+		"Agent name: /root",
+		`First context window id: ${identity.firstWindowId}`,
+		`Current context window id: ${identity.currentWindowId}`,
+	];
+	if (identity.previousWindowId) lines.push(`Previous context window id: ${identity.previousWindowId}`);
+	if (checkpoint) {
+		lines.push("Checkpoint successfully written:");
+		lines.push(`  Read this note before doing anything else with notes action "read_file": ${JSON.stringify(checkpoint.path)}`);
+	}
+	if (threadHint) lines.push(threadHint);
+	lines.push("</context_window>");
+	return `${CONTEXT_WINDOW_GUIDANCE}\n\n${lines.join("\n")}`;
+}
+
+export function renderContextWindowReminder(remainingTokens: number): string {
+	return `<context_window_reminder>
+Only ${Math.max(0, Math.floor(remainingTokens))} context tokens remain. Checkpoint the active request, state and known history IDs in notes, then call new_context; no conversation summary carries over.
+</context_window_reminder>`;
+}
+
+export const CONTEXT_WINDOW_FALLBACK_MESSAGE = `<context_window_reminder>
+Context exhausted. Do not continue or answer. Make exactly one notes write or append call that checkpoints the active request, state and known history IDs, then call new_context. Use no other tools before rollover.
+</context_window_reminder>`;
+
+export function isContextWindowBoundary(
+	message: AgentMessage,
+): message is Extract<AgentMessage, { role: "custom" }> & {
+	details: CodexContextManagementMessageDetails;
+} {
+	return (
+		message.role === "custom" &&
+		message.customType === CODEX_CONTEXT_WINDOW_MESSAGE_TYPE &&
+		isCodexContextManagementMessageDetails(message.details) &&
+		message.details.contextManagement.kind === "window"
+	);
+}
+
+export function sendContextWindowMessage(
+	pi: ExtensionAPI,
+	content: string,
+	kind: ContextManagementMessageKind,
+	identity: ContextWindowIdentity,
+	options: { triggerTurn: boolean; sessionId?: string },
+	trimPreviousWindow = false,
+): void {
+	const details: CodexContextManagementMessageDetails = {
+		protocol: CONTEXT_MANAGEMENT_PROTOCOL,
+		id: randomUUID(),
+		...(options.sessionId ? { sessionId: options.sessionId } : {}),
+		contextManagement: {
+			protocol: CONTEXT_MANAGEMENT_PROTOCOL,
+			kind,
+			...identity,
+			...(trimPreviousWindow ? { trimPreviousWindow: true as const } : {}),
+		},
+	};
+	pi.sendMessage({
+		customType: CODEX_CONTEXT_WINDOW_MESSAGE_TYPE,
+		content,
+		display: true,
+		details,
+	}, options.triggerTurn
+		? { deliverAs: "steer", triggerTurn: true }
+		: { triggerTurn: false });
+}