pi-openai-toolkit 0.14.8 → 0.14.10

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

@@ -1,31 +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;
-}
+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/context-management/messages.ts

@@ -1,112 +1,115 @@
-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 });
-}
+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>
+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(
+	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("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>");
+	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 });
+}