pi-openai-toolkit 0.9.0 → 0.11.0

package/src/codex-astra/effort-planner.ts

@@ -0,0 +1,175 @@
+import { createHash } from "node:crypto";
+
+/**
+ * Stable request-level reasoning effort via `configuration_update` input items
+ * (GPT-6 Astra), ported from Oh My Pi (`@oh-my-pi/pi-ai`, MIT licensed,
+ * Copyright (c) 2025-2026 Can Bölük / Stencil Labs) to an extension-side
+ * payload rewrite.
+ *
+ * The request-level `reasoning.effort` is pinned to the value of the session's
+ * first request so the cached prompt prefix survives an effort change. Each
+ * later change is carried as a `configuration_update` item inserted at the
+ * tail of the transcript — before the user message it takes effect on, or
+ * after the latest tool result when the level changes inside a tool loop — and
+ * replayed at that position on every subsequent request until another update
+ * overrides it.
+ *
+ * Wire constraints (verified upstream against the Codex backend): only
+ * `gpt-6-astra` accepts the item type, consecutive updates are rejected, and
+ * `/responses/compact` rejects histories containing them — compaction
+ * requests are built outside this planner and never carry the items.
+ */
+
+/** `configuration_update` input item; only `reasoning.effort` is updatable. */
+export type ConfigurationUpdateItem = {
+	type: "configuration_update";
+	reasoning: { effort: string };
+};
+
+export type PlannableInputItem = {
+	type?: string | null;
+	role?: string;
+	id?: string | null;
+	status?: string | null;
+	[key: string]: unknown;
+};
+
+type EffortTransition = {
+	/** Input-array position the item is spliced into (before `input[index]`). */
+	index: number;
+	/** Fingerprint of `input[index - 1]` at record time; a mismatch means the history was rewritten. */
+	anchor: string;
+	effort: string;
+};
+
+/** Per-conversation effort baseline and recorded transitions. */
+export type EffortControlState = {
+	baseEffort?: string;
+	currentEffort?: string;
+	transitions: EffortTransition[];
+};
+
+export type EffortPlanResult = {
+	/** The request-level effort that must accompany the returned input. */
+	effort: string;
+	/** Number of `configuration_update` items spliced into this request. */
+	spliced: number;
+};
+
+export function createEffortControlState(): EffortControlState {
+	return { transitions: [] };
+}
+
+const MAX_EFFORT_CONTROL_STATES = 16;
+
+/**
+ * Fetch (or create) the control state for one conversation from a bounded
+ * LRU map, refreshing its slot.
+ */
+export function getEffortControlState(states: Map<string, EffortControlState>, key: string): EffortControlState {
+	const existing = states.get(key);
+	if (existing) {
+		states.delete(key);
+		states.set(key, existing);
+		return existing;
+	}
+	const created = createEffortControlState();
+	states.set(key, created);
+	if (states.size > MAX_EFFORT_CONTROL_STATES) {
+		const oldest = states.keys().next().value;
+		if (oldest !== undefined) states.delete(oldest);
+	}
+	return created;
+}
+
+/**
+ * Fingerprint of the item a transition sits after. Output-only lifecycle
+ * fields are excluded: a live response item carries `id`/`status` that the
+ * sanitized replay of the same item drops.
+ */
+function transitionAnchor(input: readonly PlannableInputItem[], index: number): string {
+	if (index === 0) return "";
+	const item = input[index - 1];
+	if (!item) return "";
+	const { id: _id, status: _status, ...stable } = item;
+	return createHash("sha1").update(JSON.stringify(stable)).digest("hex");
+}
+
+function resetEffortControlState(state: EffortControlState): void {
+	state.baseEffort = undefined;
+	state.currentEffort = undefined;
+	state.transitions = [];
+}
+
+/**
+ * Discard the baseline when the request no longer continues the conversation
+ * it was captured for: a wire history that shrank or was rewritten under a
+ * recorded transition (compaction, branch switch, `/clear`). The next request
+ * re-baselines from its own effort, which is what the API asks for after
+ * compaction anyway.
+ */
+function syncEffortControlState(state: EffortControlState, input: readonly PlannableInputItem[]): void {
+	for (const transition of state.transitions) {
+		if (transition.index > input.length || transition.anchor !== transitionAnchor(input, transition.index)) {
+			resetEffortControlState(state);
+			return;
+		}
+	}
+}
+
+/**
+ * Pin the request-level effort to the session baseline and splice pending
+ * `configuration_update` items into a copy of `input`.
+ *
+ * `input` is the freshly built transcript for this request, without any
+ * `configuration_update` items. `requested` is the wire effort the caller
+ * would otherwise send at the request level.
+ */
+export function planStableEffort(
+	state: EffortControlState,
+	input: readonly PlannableInputItem[],
+	requested: string,
+): { input: Array<PlannableInputItem | ConfigurationUpdateItem>; result: EffortPlanResult } {
+	const next: Array<PlannableInputItem | ConfigurationUpdateItem> = [...input];
+	syncEffortControlState(state, next);
+	if (state.baseEffort === undefined) {
+		state.baseEffort = requested;
+		state.currentEffort = requested;
+		return { input: next, result: { effort: requested, spliced: 0 } };
+	}
+	if (state.currentEffort !== requested) {
+		const last = next[next.length - 1];
+		const index = last && last.role === "user" ? next.length - 1 : next.length;
+		const existing = state.transitions.find((transition) => transition.index === index);
+		if (existing) {
+			existing.effort = requested;
+		} else {
+			state.transitions.push({ index, anchor: transitionAnchor(next, index), effort: requested });
+		}
+		// A change back to the effort already in force at that position is a
+		// no-op on the wire; drop it rather than send a redundant item.
+		let preceding = state.baseEffort;
+		let precedingIndex = -1;
+		for (const transition of state.transitions) {
+			if (transition.index < index && transition.index > precedingIndex) {
+				preceding = transition.effort;
+				precedingIndex = transition.index;
+			}
+		}
+		if (requested === preceding) {
+			state.transitions = state.transitions.filter((transition) => transition.index !== index);
+		}
+		state.currentEffort = requested;
+	}
+	// Splice in ascending order so each insertion offsets only the ones after it.
+	state.transitions.sort((a, b) => a.index - b.index);
+	let offset = 0;
+	for (const transition of state.transitions) {
+		next.splice(transition.index + offset, 0, {
+			type: "configuration_update",
+			reasoning: { effort: transition.effort },
+		});
+		offset++;
+	}
+	return { input: next, result: { effort: state.baseEffort, spliced: state.transitions.length } };
+}

package/src/codex-astra/extension.ts

@@ -0,0 +1,123 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadToolkitConfig } from "../config";
+import { isExactModelAllowed } from "../model-scope";
+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,
+	loadConfig: typeof loadToolkitConfig = loadToolkitConfig,
+): 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 {
+			const { config } = loadConfig();
+			const astra = config.codexAstra;
+			if (!astra.enabled || astra.models.length === 0) return undefined;
+
+			const model = ctx.model;
+			if (!model || model.api !== "openai-codex-responses") return undefined;
+			if (!isExactModelAllowed(model, astra.models)) 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/compact-client.ts

@@ -1,5 +1,6 @@
 import { writeDebugArtifact } from "./debug";
 import { buildResponsesRequestHeaders } from "./responses-headers";
+import { stripConfigurationUpdateItems } from "./remote-v2-client";
 import type { NativeCompactionRuntime } from "./runtime";
 import type { NativeCompactionRequestBody } from "./serializer";
 import type { ArtifactContext, CompactionConfig } from "./types";
@@ -114,7 +115,10 @@ export function extractCompactedSummaryText(output: readonly unknown[]): string
 
 function toHeaders(runtime: NativeCompactionRuntime): Record<string, string> {
 	return Object.fromEntries(
-		buildResponsesRequestHeaders(runtime, { accept: JSON_CONTENT_TYPE }).entries(),
+		buildResponsesRequestHeaders(runtime, {
+			accept: JSON_CONTENT_TYPE,
+			sessionId: runtime.sessionId,
+		}).entries(),
 	);
 }
 
@@ -133,7 +137,13 @@ function writeCompactArtifact(
 export async function executeNativeCompaction(
 	options: ExecuteNativeCompactionOptions,
 ): Promise<NativeCompactionClientResult> {
-	const { runtime, request, signal, settings, context } = options;
+	const { runtime, signal, settings, context } = options;
+	// Same Astra-history rejection as remote v2: `/responses/compact` rejects
+	// `configuration_update` items, so a replayed history never carries one.
+	const request: NativeCompactionRequestBody = {
+		...options.request,
+		input: stripConfigurationUpdateItems(options.request.input) as NativeCompactionRequestBody["input"],
+	};
 	const headers = toHeaders(runtime);
 
 	if (signal?.aborted) {

package/src/config.ts

@@ -8,15 +8,28 @@ import {
 	DEFAULT_AUTO_COMPACTION_CONFIG,
 	DEFAULT_AUTO_MODE_CONFIG,
 	DEFAULT_IMAGE_GENERATION_CONFIG,
+	DEFAULT_CODEX_ASTRA_CONFIG,
 	DEFAULT_NATIVE_FALLBACK_CONFIG,
 	DEFAULT_WEB_SEARCH_CONFIG,
 	RESPONSES_COMPACT_CAPABLE_APIS,
+	BREAKER_LIMIT_MAX,
+	BREAKER_LIMIT_MIN,
+	BREAKER_WINDOW_MAX,
+	BREAKER_WINDOW_MIN,
+	CLASSIFIER_MAX_LAG_MAX,
+	CLASSIFIER_MAX_LAG_MIN,
+	DEFAULT_CLASSIFIER_TIMEOUT_MS,
+	EVIDENCE_ROUNDS_MAX,
+	EVIDENCE_ROUNDS_MIN,
 	REVIEWER_TIMEOUT_MAX_MS,
 	REVIEWER_TIMEOUT_MIN_MS,
 	THINKING_LEVELS,
 	TOOLKIT_ID,
+	type AutoModeCircuitBreakerConfig,
+	type AutoModeClassifierConfig,
 	type AutoModeConfig,
 	type AutoModeGate,
+	type CodexAstraConfig,
 	type CompactionConfig,
 	type ImageGenerationConfig,
 	type LoadedToolkitConfig,
@@ -28,7 +41,7 @@ import {
 export const CONFIG_DIR = path.join(os.homedir(), ".pi", "agent", "extensions", TOOLKIT_ID);
 export const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
 
-const TOP_LEVEL_FIELDS = new Set(["compaction", "webSearch", "imageGeneration", "autoMode"]);
+const TOP_LEVEL_FIELDS = new Set(["compaction", "webSearch", "imageGeneration", "autoMode", "codexAstra"]);
 const COMPACTION_FIELDS = new Set([
 	"enabled",
 	"allowCompactionContinuityBreak",
@@ -47,7 +60,22 @@ const NATIVE_FALLBACK_FIELDS = new Set(["enabled", "model", "thinkingLevel"]);
 const AUTO_COMPACTION_FIELDS = new Set(["enabled", "continuation", "unsupportedFallback", "reserveTokens"]);
 const WEB_SEARCH_FIELDS = new Set(["enabled", "models"]);
 const IMAGE_GENERATION_FIELDS = new Set(["enabled"]);
-const AUTO_MODE_FIELDS = new Set(["enabled", "models", "reviewerModel", "gate", "extraTools", "timeoutMs"]);
+const CODEX_ASTRA_FIELDS = new Set(["enabled", "models"]);
+const AUTO_MODE_FIELDS = new Set([
+	"enabled",
+	"models",
+	"reviewerModel",
+	"gate",
+	"extraTools",
+	"timeoutMs",
+	"transcript",
+	"evidenceTools",
+	"maxEvidenceRounds",
+	"classifier",
+	"circuitBreaker",
+]);
+const AUTO_MODE_CLASSIFIER_FIELDS = new Set(["enabled", "model", "timeoutMs", "maxLag"]);
+const AUTO_MODE_BREAKER_FIELDS = new Set(["consecutiveDenials", "recentDenials", "windowSize"]);
 
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return !!value && typeof value === "object" && !Array.isArray(value);
@@ -156,6 +184,21 @@ function toNonNegativeInteger(value: unknown, fieldPath: string, warnings: strin
 	return undefined;
 }
 
+function toBoundedInteger(
+	value: unknown,
+	fieldPath: string,
+	warnings: string[],
+	min: number,
+	max: number,
+): number | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value === "number" && Number.isInteger(value) && Number.isFinite(value) && value >= min && value <= max) {
+		return value;
+	}
+	warnings.push(`Ignoring ${fieldPath}: expected an integer between ${min} and ${max}.`);
+	return undefined;
+}
+
 function toSupportedApis(
 	value: unknown,
 	fieldPath: string,
@@ -229,10 +272,16 @@ function cloneDefaults(): ToolkitConfig {
 			models: [...DEFAULT_WEB_SEARCH_CONFIG.models],
 		},
 		imageGeneration: { ...DEFAULT_IMAGE_GENERATION_CONFIG },
+		codexAstra: {
+			...DEFAULT_CODEX_ASTRA_CONFIG,
+			models: [...DEFAULT_CODEX_ASTRA_CONFIG.models],
+		},
 		autoMode: {
 			...DEFAULT_AUTO_MODE_CONFIG,
 			models: [...DEFAULT_AUTO_MODE_CONFIG.models],
 			extraTools: [...DEFAULT_AUTO_MODE_CONFIG.extraTools],
+			classifier: { ...DEFAULT_AUTO_MODE_CONFIG.classifier },
+			circuitBreaker: { ...DEFAULT_AUTO_MODE_CONFIG.circuitBreaker },
 		},
 	};
 }
@@ -375,6 +424,20 @@ function applyImageGenerationConfig(
 		toBoolean(raw.enabled, "imageGeneration.enabled", warnings) ?? resolved.enabled;
 }
 
+function applyCodexAstraConfig(
+	raw: Record<string, unknown>,
+	resolved: CodexAstraConfig,
+	warnings: string[],
+): void {
+	warnUnknownFields(raw, CODEX_ASTRA_FIELDS, "codexAstra", warnings);
+	resolved.enabled = toBoolean(raw.enabled, "codexAstra.enabled", warnings) ?? resolved.enabled;
+
+	const models = toStringList(raw.models, "codexAstra.models", warnings);
+	if (models !== undefined) {
+		resolved.models = models;
+	}
+}
+
 function applyAutoModeConfig(
 	raw: Record<string, unknown>,
 	resolved: AutoModeConfig,
@@ -404,6 +467,116 @@ function applyAutoModeConfig(
 	if (timeoutMs !== undefined) {
 		resolved.timeoutMs = timeoutMs;
 	}
+
+	resolved.transcript = toBoolean(raw.transcript, "autoMode.transcript", warnings) ?? resolved.transcript;
+	resolved.evidenceTools =
+		toBoolean(raw.evidenceTools, "autoMode.evidenceTools", warnings) ?? resolved.evidenceTools;
+
+	const maxEvidenceRounds = toBoundedInteger(
+		raw.maxEvidenceRounds,
+		"autoMode.maxEvidenceRounds",
+		warnings,
+		EVIDENCE_ROUNDS_MIN,
+		EVIDENCE_ROUNDS_MAX,
+	);
+	if (maxEvidenceRounds !== undefined) {
+		resolved.maxEvidenceRounds = maxEvidenceRounds;
+	}
+
+	if (raw.classifier !== undefined) {
+		if (isRecord(raw.classifier)) {
+			applyAutoModeClassifierConfig(raw.classifier, resolved.classifier, warnings);
+		} else {
+			warnings.push("Ignoring autoMode.classifier: expected a JSON object.");
+		}
+	}
+
+	if (raw.circuitBreaker !== undefined) {
+		if (isRecord(raw.circuitBreaker)) {
+			applyAutoModeBreakerConfig(raw.circuitBreaker, resolved.circuitBreaker, warnings);
+		} else {
+			warnings.push("Ignoring autoMode.circuitBreaker: expected a JSON object.");
+		}
+	}
+}
+
+function applyAutoModeClassifierConfig(
+	raw: Record<string, unknown>,
+	resolved: AutoModeClassifierConfig,
+	warnings: string[],
+): void {
+	warnUnknownFields(raw, AUTO_MODE_CLASSIFIER_FIELDS, "autoMode.classifier", warnings);
+	resolved.enabled =
+		toBoolean(raw.enabled, "autoMode.classifier.enabled", warnings) ?? resolved.enabled;
+
+	const model = toModelSpec(raw.model, "autoMode.classifier.model", warnings);
+	if (model !== undefined) {
+		resolved.model = model === null ? undefined : model;
+	}
+
+	const timeoutMs =
+		toBoundedInteger(
+			raw.timeoutMs,
+			"autoMode.classifier.timeoutMs",
+			warnings,
+			REVIEWER_TIMEOUT_MIN_MS,
+			REVIEWER_TIMEOUT_MAX_MS,
+		) ?? DEFAULT_CLASSIFIER_TIMEOUT_MS;
+	if (raw.timeoutMs !== undefined) {
+		resolved.timeoutMs = timeoutMs;
+	}
+
+	const maxLag = toBoundedInteger(
+		raw.maxLag,
+		"autoMode.classifier.maxLag",
+		warnings,
+		CLASSIFIER_MAX_LAG_MIN,
+		CLASSIFIER_MAX_LAG_MAX,
+	);
+	if (maxLag !== undefined) {
+		resolved.maxLag = maxLag;
+	}
+}
+
+function applyAutoModeBreakerConfig(
+	raw: Record<string, unknown>,
+	resolved: AutoModeCircuitBreakerConfig,
+	warnings: string[],
+): void {
+	warnUnknownFields(raw, AUTO_MODE_BREAKER_FIELDS, "autoMode.circuitBreaker", warnings);
+
+	const consecutiveDenials = toBoundedInteger(
+		raw.consecutiveDenials,
+		"autoMode.circuitBreaker.consecutiveDenials",
+		warnings,
+		BREAKER_LIMIT_MIN,
+		BREAKER_LIMIT_MAX,
+	);
+	if (consecutiveDenials !== undefined) {
+		resolved.consecutiveDenials = consecutiveDenials;
+	}
+
+	const recentDenials = toBoundedInteger(
+		raw.recentDenials,
+		"autoMode.circuitBreaker.recentDenials",
+		warnings,
+		BREAKER_LIMIT_MIN,
+		BREAKER_LIMIT_MAX,
+	);
+	if (recentDenials !== undefined) {
+		resolved.recentDenials = recentDenials;
+	}
+
+	const windowSize = toBoundedInteger(
+		raw.windowSize,
+		"autoMode.circuitBreaker.windowSize",
+		warnings,
+		BREAKER_WINDOW_MIN,
+		BREAKER_WINDOW_MAX,
+	);
+	if (windowSize !== undefined) {
+		resolved.windowSize = windowSize;
+	}
 }
 
 /**
@@ -452,6 +625,14 @@ export function loadToolkitConfig(configPath: string = CONFIG_PATH): LoadedToolk
 				warnings.push("Ignoring autoMode: expected a JSON object.");
 			}
 		}
+
+		if (raw.codexAstra !== undefined) {
+			if (isRecord(raw.codexAstra)) {
+				applyCodexAstraConfig(raw.codexAstra, resolved.codexAstra, warnings);
+			} else {
+				warnings.push("Ignoring codexAstra: expected a JSON object.");
+			}
+		}
 	}
 
 	resolved.compaction.artifactRoot = resolveConfiguredPath(

package/src/remote-v2-client.ts

@@ -119,16 +119,32 @@ function toHeaders(runtime: NativeCompactionRuntime): Record<string, string> {
 		buildResponsesRequestHeaders(runtime, {
 			accept: SSE_CONTENT_TYPE,
 			contentType: JSON_CONTENT_TYPE,
+			sessionId: runtime.sessionId,
 		}).entries(),
 	);
 }
 
+/**
+ * Codex `/responses` rejects histories that mix this Astra-only item into a
+ * compaction request (verified upstream in Oh My Pi: the compaction path is
+ * deliberately built outside the effort planner). The host never emits the
+ * item into a payload we would replay today, but the item is transparently
+ * carried by our opaque-window replay, so strip it defensively on every
+ * remote v2 request regardless of API family.
+ */
+export function stripConfigurationUpdateItems(input: readonly unknown[]): unknown[] {
+	return input.filter((item) => !isRecord(item) || item["type"] !== "configuration_update");
+}
+
 export function buildRemoteV2CompactionRequest(
 	request: NativeCompactionRequestBody,
 ): RemoteV2CompactionRequestBody {
 	return {
 		...structuredClone(request),
-		input: [...structuredClone(request.input), { type: "compaction_trigger" }],
+		input: [
+			...(stripConfigurationUpdateItems(structuredClone(request.input)) as ResponsesInputItem[]),
+			{ type: "compaction_trigger" },
+		],
 		store: false,
 		stream: true,
 	};

package/src/responses-headers.ts

@@ -5,6 +5,7 @@ export type ResponsesHeaderRuntime = {
 	api: string;
 	apiKey: string;
 	headers?: ProviderHeaders;
+	sessionId?: string;
 	currentModel: {
 		headers?: ProviderHeaders;
 	};
@@ -38,9 +39,34 @@ function buildCodexUserAgent(): string {
 	return `pi (${platform}; ${arch})`;
 }
 
+/**
+ * The Codex backend version-gates model availability on the `version` header
+ * (the pinned @openai/codex client version). `gpt-6-astra` requires >= 0.153.0;
+ * an older or absent pin makes the SKU invisible to discovery and rejects
+ * requests that name it. Keep this in sync with the newest gate Oh My Pi pins
+ * in @oh-my-pi/pi-wire/codex (`CODEX_CLIENT_VERSION`).
+ */
+export const CODEX_CLIENT_VERSION = "0.153.0";
+
+/** Prompt cache keys are clamped by the same host rule (`OPENAI_PROMPT_CACHE_KEY_MAX_LENGTH`). */
+const CODEX_SESSION_ID_MAX_LENGTH = 64;
+
+export function clampCodexSessionId(sessionId: string | undefined): string | undefined {
+	if (!sessionId) return undefined;
+	const chars = Array.from(sessionId);
+	return chars.length <= CODEX_SESSION_ID_MAX_LENGTH ? sessionId : chars.slice(0, CODEX_SESSION_ID_MAX_LENGTH).join("");
+}
+
+export type ResponsesHeaderOptions = {
+	accept: string;
+	contentType?: string;
+	/** Conversation identity for Codex cache-affinity headers; clamped to 64 chars here. */
+	sessionId?: string;
+};
+
 export function buildResponsesRequestHeaders(
 	runtime: ResponsesHeaderRuntime,
-	options: { accept: string; contentType?: string },
+	options: ResponsesHeaderOptions,
 ): Headers {
 	const headers = new Headers(
 		mergeProviderHeaders(runtime.currentModel.headers, runtime.headers),
@@ -57,6 +83,21 @@ export function buildResponsesRequestHeaders(
 		headers.set("originator", "pi");
 		headers.set("user-agent", buildCodexUserAgent());
 		headers.set("openai-beta", "responses=experimental");
+		// Codex backend gating: a request without a new-enough `version` never
+		// reaches model SKUs that arrived behind the gate (gpt-6-astra).
+		headers.set("version", CODEX_CLIENT_VERSION);
+		// Prompt-cache affinity rides on the conversation identity: the backend
+		// keeps a conversation's cache prefix on the node that wrote it, so our
+		// synthetic compaction requests must present the same id the live
+		// transcript requests used, or every compact pays a full cache miss.
+		const sessionId = clampCodexSessionId(options.sessionId ?? runtime.sessionId);
+		if (sessionId) {
+			// Header names match the installed host's live-request builder
+			// (`buildSSEHeaders`: `session-id` + `x-client-request-id`) so our
+			// synthetic requests land in the same conversation affinity group.
+			headers.set("session-id", sessionId);
+			headers.set("x-client-request-id", sessionId);
+		}
 	}
 
 	return headers;