pi-openai-toolkit 0.14.3 → 0.14.5

package/src/image-generation/types.ts

@@ -1,184 +1,189 @@
-export const IMAGE_GENERATION_TOOL_NAME = "openai_generate_image";
-export const IMAGE_GENERATION_MODEL = "gpt-image-2" as const;
-export const IMAGE_GENERATION_MIME_TYPE = "image/png" as const;
-export const IMAGE_GENERATION_CAPABLE_APIS = [
-	"openai-responses",
-	"openai-codex-responses",
-] as const;
-export const IMAGE_GENERATION_SIZES = [
-	"auto",
-	"1024x1024",
-	"1536x1024",
-	"1024x1536",
-] as const;
-export const IMAGE_GENERATION_QUALITIES = ["auto", "low", "medium", "high"] as const;
-
-export const MAX_IMAGE_PROMPT_CHARS = 20_000;
-export const MAX_REFERENCE_IMAGE_COUNT = 5;
-export const MAX_REFERENCE_IMAGE_BYTES = 20 * 1024 * 1024;
-export const MAX_TOTAL_REFERENCE_IMAGE_BYTES = 50 * 1024 * 1024;
-export const MAX_GENERATED_IMAGE_BYTES = 32 * 1024 * 1024;
-export const MAX_IMAGE_RESPONSE_BYTES = 48 * 1024 * 1024;
-export const MAX_IMAGE_ERROR_BYTES = 64 * 1024;
-export const IMAGE_REQUEST_TIMEOUT_MS = 5 * 60 * 1000;
-export const MAX_IMAGE_PATH_CHARS = 4096;
-export const MAX_IMAGE_DIAGNOSTIC_CHARS = 4096;
-export const MAX_IMAGE_IDENTIFIER_CHARS = 256;
-export const MAX_IMAGE_DIMENSION = 100_000;
-
-export type ImageGenerationCapableApi = (typeof IMAGE_GENERATION_CAPABLE_APIS)[number];
-export type ImageGenerationSize = (typeof IMAGE_GENERATION_SIZES)[number];
-export type ImageGenerationQuality = (typeof IMAGE_GENERATION_QUALITIES)[number];
-export type ImageGenerationAction = "generate" | "edit";
-export type ReferenceImageMimeType = "image/png" | "image/jpeg" | "image/webp";
-
-export type ImageGenerationModel = {
-	api?: string;
-	provider?: string;
-	id?: string;
-};
-
-export type GenerateImageParams = {
-	prompt: string;
-	referenceImagePaths?: string[] | null;
-	outputPath?: string | null;
-	size?: ImageGenerationSize;
-	quality?: ImageGenerationQuality;
-};
-
-export type NormalizedGenerateImageParams = {
-	prompt: string;
-	referenceImagePaths: string[];
-	outputPath?: string;
-	size: ImageGenerationSize;
-	quality: ImageGenerationQuality;
-	action: ImageGenerationAction;
-};
-
-export type PreparedReferenceImage = {
-	path: string;
-	mimeType: ReferenceImageMimeType;
-	bytes: Buffer;
-};
-
-export type ParsedGeneratedImage = {
-	bytes: Buffer;
-	imageCallId: string;
-	responseId?: string;
-	revisedPrompt?: string;
-	width: number;
-	height: number;
-};
-
-export type ImageGenerationDetails = {
-	artifactPath: string;
-	outputPath?: string;
-	routingModel: string;
-	imageModel: typeof IMAGE_GENERATION_MODEL;
-	imageCallId: string;
-	responseId?: string;
-	mimeType: typeof IMAGE_GENERATION_MIME_TYPE;
-	byteCount: number;
-	width: number;
-	height: number;
-	edited: boolean;
-	referenceCount: number;
-	revisedPrompt?: string;
-	warning?: string;
-};
-
-export type ImageGenerationExecutionResult = {
-	details: ImageGenerationDetails;
-	text: string;
-};
-
-export type ImageGenerationFailureCode =
-	| "aborted"
-	| "timeout"
-	| "disabled"
-	| "unsupported-model"
-	| "missing-runtime"
-	| "invalid-parameters"
-	| "reference-input-invalid"
-	| "reference-upload-approval-required"
-	| "reference-upload-declined"
-	| "output-path-invalid"
-	| "output-path-approval-required"
-	| "output-path-declined"
-	| "authentication"
-	| "rate-limit"
-	| "request-rejected"
-	| "backend-unavailable"
-	| "network"
-	| "oversized-response"
-	| "malformed-response"
-	| "no-image"
-	| "artifact-write-failed";
-
-export class ImageGenerationError extends Error {
-	readonly code: ImageGenerationFailureCode;
-
-	constructor(code: ImageGenerationFailureCode, message: string) {
-		super(message);
-		this.name = "ImageGenerationError";
-		this.code = code;
-	}
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return !!value && typeof value === "object" && !Array.isArray(value);
-}
-
-function isBoundedString(value: unknown, maxChars: number): value is string {
-	return typeof value === "string" && value.length > 0 && value.length <= maxChars;
-}
-
-export function isImageGenerationDetails(value: unknown): value is ImageGenerationDetails {
-	if (!isRecord(value)) return false;
-	return (
-		isBoundedString(value.artifactPath, MAX_IMAGE_PATH_CHARS) &&
-		(value.outputPath === undefined || isBoundedString(value.outputPath, MAX_IMAGE_PATH_CHARS)) &&
-		isBoundedString(value.routingModel, MAX_IMAGE_DIAGNOSTIC_CHARS) &&
-		value.imageModel === IMAGE_GENERATION_MODEL &&
-		isBoundedString(value.imageCallId, MAX_IMAGE_IDENTIFIER_CHARS) &&
-		(value.responseId === undefined || isBoundedString(value.responseId, MAX_IMAGE_IDENTIFIER_CHARS)) &&
-		value.mimeType === IMAGE_GENERATION_MIME_TYPE &&
-		typeof value.byteCount === "number" &&
-		Number.isInteger(value.byteCount) &&
-		value.byteCount > 0 &&
-		value.byteCount <= MAX_GENERATED_IMAGE_BYTES &&
-		typeof value.width === "number" &&
-		Number.isInteger(value.width) &&
-		value.width > 0 &&
-		value.width <= MAX_IMAGE_DIMENSION &&
-		typeof value.height === "number" &&
-		Number.isInteger(value.height) &&
-		value.height > 0 &&
-		value.height <= MAX_IMAGE_DIMENSION &&
-		typeof value.edited === "boolean" &&
-		typeof value.referenceCount === "number" &&
-		Number.isInteger(value.referenceCount) &&
-		value.referenceCount >= 0 &&
-		value.referenceCount <= MAX_REFERENCE_IMAGE_COUNT &&
-		(value.revisedPrompt === undefined || isBoundedString(value.revisedPrompt, MAX_IMAGE_DIAGNOSTIC_CHARS)) &&
-		(value.warning === undefined || isBoundedString(value.warning, MAX_IMAGE_DIAGNOSTIC_CHARS))
-	);
-}
-
-export function sanitizeImageDiagnostic(value: unknown, fallback: string): string {
-	if (typeof value !== "string") return fallback;
-	const normalized = value
-		.replace(/data:image\/[a-z0-9.+-]+;base64,[A-Za-z0-9+/=]+/gi, "[REDACTED_IMAGE_DATA]")
-		.replace(/[A-Za-z0-9+/]{128,}={0,2}/g, "[REDACTED_BASE64]")
-		.replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [REDACTED]")
-		.replace(
-			/\b(authorization|api[-_ ]?key|access[-_ ]?token|refresh[-_ ]?token|account[-_ ]?id|cookie)\s*[:=]\s*[^\s,;]+/gi,
-			"$1: [REDACTED]",
-		)
-		.replace(/\bsk-[A-Za-z0-9_-]{8,}\b/g, "[REDACTED]")
-		.replace(/[\u0000-\u001f\u007f]+/g, " ")
-		.replace(/\s+/g, " ")
-		.trim();
-	if (!normalized) return fallback;
-	return normalized.slice(0, MAX_IMAGE_DIAGNOSTIC_CHARS);
-}
+export const IMAGE_GENERATION_TOOL_NAME = "openai_generate_image";
+export const IMAGE_GENERATION_MIME_TYPE = "image/png" as const;
+export const IMAGE_GENERATION_CAPABLE_APIS = [
+	"openai-responses",
+	"openai-codex-responses",
+] as const;
+export const IMAGE_GENERATION_SIZES = [
+	"auto",
+	"1024x1024",
+	"1536x1024",
+	"1024x1536",
+] as const;
+export const IMAGE_GENERATION_QUALITIES = ["auto", "low", "medium", "high"] as const;
+
+export const MAX_IMAGE_PROMPT_CHARS = 20_000;
+export const MAX_REFERENCE_IMAGE_COUNT = 5;
+export const MAX_REFERENCE_IMAGE_BYTES = 20 * 1024 * 1024;
+export const MAX_TOTAL_REFERENCE_IMAGE_BYTES = 50 * 1024 * 1024;
+export const MAX_GENERATED_IMAGE_BYTES = 32 * 1024 * 1024;
+export const MAX_IMAGE_RESPONSE_BYTES = 48 * 1024 * 1024;
+export const MAX_IMAGE_ERROR_BYTES = 64 * 1024;
+export const IMAGE_REQUEST_TIMEOUT_MS = 5 * 60 * 1000;
+export const MAX_IMAGE_PATH_CHARS = 4096;
+export const MAX_IMAGE_DIAGNOSTIC_CHARS = 4096;
+export const MAX_IMAGE_IDENTIFIER_CHARS = 256;
+/** Upper bound for a configured or requested `image_generation` model id. */
+export const MAX_IMAGE_MODEL_ID_CHARS = 256;
+export const MAX_IMAGE_DIMENSION = 100_000;
+
+export type ImageGenerationCapableApi = (typeof IMAGE_GENERATION_CAPABLE_APIS)[number];
+export type ImageGenerationSize = (typeof IMAGE_GENERATION_SIZES)[number];
+export type ImageGenerationQuality = (typeof IMAGE_GENERATION_QUALITIES)[number];
+export type ImageGenerationAction = "generate" | "edit";
+export type ReferenceImageMimeType = "image/png" | "image/jpeg" | "image/webp";
+
+export type ImageGenerationModel = {
+	api?: string;
+	provider?: string;
+	id?: string;
+};
+
+export type GenerateImageParams = {
+	prompt: string;
+	referenceImagePaths?: string[] | null;
+	outputPath?: string | null;
+	size?: ImageGenerationSize;
+	quality?: ImageGenerationQuality;
+	/** Optional bare image model id that must exist in `imageGeneration.models`. */
+	model?: string | null;
+};
+
+export type NormalizedGenerateImageParams = {
+	prompt: string;
+	referenceImagePaths: string[];
+	outputPath?: string;
+	size: ImageGenerationSize;
+	quality: ImageGenerationQuality;
+	action: ImageGenerationAction;
+	/** Trimmed requested model id, or undefined when the caller omitted it. */
+	model?: string;
+};
+
+export type PreparedReferenceImage = {
+	path: string;
+	mimeType: ReferenceImageMimeType;
+	bytes: Buffer;
+};
+
+export type ParsedGeneratedImage = {
+	bytes: Buffer;
+	imageCallId: string;
+	responseId?: string;
+	revisedPrompt?: string;
+	width: number;
+	height: number;
+};
+
+export type ImageGenerationDetails = {
+	artifactPath: string;
+	outputPath?: string;
+	routingModel: string;
+	imageModel: string;
+	imageCallId: string;
+	responseId?: string;
+	mimeType: typeof IMAGE_GENERATION_MIME_TYPE;
+	byteCount: number;
+	width: number;
+	height: number;
+	edited: boolean;
+	referenceCount: number;
+	revisedPrompt?: string;
+	warning?: string;
+};
+
+export type ImageGenerationExecutionResult = {
+	details: ImageGenerationDetails;
+	text: string;
+};
+
+export type ImageGenerationFailureCode =
+	| "aborted"
+	| "timeout"
+	| "disabled"
+	| "unsupported-model"
+	| "missing-runtime"
+	| "invalid-parameters"
+	| "reference-input-invalid"
+	| "reference-upload-approval-required"
+	| "reference-upload-declined"
+	| "output-path-invalid"
+	| "output-path-approval-required"
+	| "output-path-declined"
+	| "authentication"
+	| "rate-limit"
+	| "request-rejected"
+	| "backend-unavailable"
+	| "network"
+	| "oversized-response"
+	| "malformed-response"
+	| "no-image"
+	| "artifact-write-failed";
+
+export class ImageGenerationError extends Error {
+	readonly code: ImageGenerationFailureCode;
+
+	constructor(code: ImageGenerationFailureCode, message: string) {
+		super(message);
+		this.name = "ImageGenerationError";
+		this.code = code;
+	}
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function isBoundedString(value: unknown, maxChars: number): value is string {
+	return typeof value === "string" && value.trim().length > 0 && value.length <= maxChars;
+}
+
+export function isImageGenerationDetails(value: unknown): value is ImageGenerationDetails {
+	if (!isRecord(value)) return false;
+	return (
+		isBoundedString(value.artifactPath, MAX_IMAGE_PATH_CHARS) &&
+		(value.outputPath === undefined || isBoundedString(value.outputPath, MAX_IMAGE_PATH_CHARS)) &&
+		isBoundedString(value.routingModel, MAX_IMAGE_DIAGNOSTIC_CHARS) &&
+		isBoundedString(value.imageModel, MAX_IMAGE_MODEL_ID_CHARS) &&
+		isBoundedString(value.imageCallId, MAX_IMAGE_IDENTIFIER_CHARS) &&
+		(value.responseId === undefined || isBoundedString(value.responseId, MAX_IMAGE_IDENTIFIER_CHARS)) &&
+		value.mimeType === IMAGE_GENERATION_MIME_TYPE &&
+		typeof value.byteCount === "number" &&
+		Number.isInteger(value.byteCount) &&
+		value.byteCount > 0 &&
+		value.byteCount <= MAX_GENERATED_IMAGE_BYTES &&
+		typeof value.width === "number" &&
+		Number.isInteger(value.width) &&
+		value.width > 0 &&
+		value.width <= MAX_IMAGE_DIMENSION &&
+		typeof value.height === "number" &&
+		Number.isInteger(value.height) &&
+		value.height > 0 &&
+		value.height <= MAX_IMAGE_DIMENSION &&
+		typeof value.edited === "boolean" &&
+		typeof value.referenceCount === "number" &&
+		Number.isInteger(value.referenceCount) &&
+		value.referenceCount >= 0 &&
+		value.referenceCount <= MAX_REFERENCE_IMAGE_COUNT &&
+		(value.revisedPrompt === undefined || isBoundedString(value.revisedPrompt, MAX_IMAGE_DIAGNOSTIC_CHARS)) &&
+		(value.warning === undefined || isBoundedString(value.warning, MAX_IMAGE_DIAGNOSTIC_CHARS))
+	);
+}
+
+export function sanitizeImageDiagnostic(value: unknown, fallback: string): string {
+	if (typeof value !== "string") return fallback;
+	const normalized = value
+		.replace(/data:image\/[a-z0-9.+-]+;base64,[A-Za-z0-9+/=]+/gi, "[REDACTED_IMAGE_DATA]")
+		.replace(/[A-Za-z0-9+/]{128,}={0,2}/g, "[REDACTED_BASE64]")
+		.replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [REDACTED]")
+		.replace(
+			/\b(authorization|api[-_ ]?key|access[-_ ]?token|refresh[-_ ]?token|account[-_ ]?id|cookie)\s*[:=]\s*[^\s,;]+/gi,
+			"$1: [REDACTED]",
+		)
+		.replace(/\bsk-[A-Za-z0-9_-]{8,}\b/g, "[REDACTED]")
+		.replace(/[\u0000-\u001f\u007f]+/g, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+	if (!normalized) return fallback;
+	return normalized.slice(0, MAX_IMAGE_DIAGNOSTIC_CHARS);
+}

package/src/responses-headers.ts

@@ -1,108 +1,108 @@
-import type { ProviderHeaders } from "@earendil-works/pi-ai";
-import { mergeProviderHeaders } from "./provider-headers";
-
-export type ResponsesHeaderRuntime = {
-	api: string;
-	apiKey: string;
-	headers?: ProviderHeaders;
-	sessionId?: string;
-	currentModel: {
-		headers?: ProviderHeaders;
-	};
-};
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return !!value && typeof value === "object" && !Array.isArray(value);
-}
-
-function decodeJwtPayload(token: string): Record<string, unknown> | undefined {
-	const parts = token.split(".");
-	if (parts.length !== 3) return undefined;
-	try {
-		const payload = JSON.parse(Buffer.from(parts[1]!, "base64url").toString("utf8")) as unknown;
-		return isRecord(payload) ? payload : undefined;
-	} catch {
-		return undefined;
-	}
-}
-
-function extractCodexAccountId(token: string): string | undefined {
-	const authClaims = decodeJwtPayload(token)?.["https://api.openai.com/auth"];
-	if (!isRecord(authClaims)) return undefined;
-	const accountId = authClaims.chatgpt_account_id;
-	return typeof accountId === "string" && accountId.trim() ? accountId.trim() : undefined;
-}
-
-function buildCodexUserAgent(): string {
-	const platform = typeof process !== "undefined" ? process.platform : "browser";
-	const arch = typeof process !== "undefined" ? process.arch : "unknown";
-	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: ResponsesHeaderOptions,
-): Headers {
-	const headers = new Headers(
-		mergeProviderHeaders(runtime.currentModel.headers, runtime.headers),
-	);
-	headers.set("accept", options.accept);
-	headers.set("content-type", options.contentType ?? "application/json");
-	if (!headers.has("authorization")) {
-		headers.set("authorization", `Bearer ${runtime.apiKey}`);
-	}
-
-	if (runtime.api === "openai-codex-responses") {
-		const accountId = extractCodexAccountId(runtime.apiKey);
-		if (accountId) headers.set("chatgpt-account-id", accountId);
-		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;
-}
-
-export const _responsesHeadersTest = {
-	extractCodexAccountId,
-};
+import type { ProviderHeaders } from "@earendil-works/pi-ai";
+import { mergeProviderHeaders } from "./provider-headers";
+
+export type ResponsesHeaderRuntime = {
+	api: string;
+	apiKey: string;
+	headers?: ProviderHeaders;
+	sessionId?: string;
+	currentModel: {
+		headers?: ProviderHeaders;
+	};
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function decodeJwtPayload(token: string): Record<string, unknown> | undefined {
+	const parts = token.split(".");
+	if (parts.length !== 3) return undefined;
+	try {
+		const payload = JSON.parse(Buffer.from(parts[1]!, "base64url").toString("utf8")) as unknown;
+		return isRecord(payload) ? payload : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function extractCodexAccountId(token: string): string | undefined {
+	const authClaims = decodeJwtPayload(token)?.["https://api.openai.com/auth"];
+	if (!isRecord(authClaims)) return undefined;
+	const accountId = authClaims.chatgpt_account_id;
+	return typeof accountId === "string" && accountId.trim() ? accountId.trim() : undefined;
+}
+
+function buildCodexUserAgent(): string {
+	const platform = typeof process !== "undefined" ? process.platform : "browser";
+	const arch = typeof process !== "undefined" ? process.arch : "unknown";
+	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: ResponsesHeaderOptions,
+): Headers {
+	const headers = new Headers(
+		mergeProviderHeaders(runtime.currentModel.headers, runtime.headers),
+	);
+	headers.set("accept", options.accept);
+	headers.set("content-type", options.contentType ?? "application/json");
+	if (!headers.has("authorization")) {
+		headers.set("authorization", `Bearer ${runtime.apiKey}`);
+	}
+
+	if (runtime.api === "openai-codex-responses") {
+		const accountId = extractCodexAccountId(runtime.apiKey);
+		if (accountId) headers.set("chatgpt-account-id", accountId);
+		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;
+}
+
+export const _responsesHeadersTest = {
+	extractCodexAccountId,
+};