@lll9p/pi-better-compaction 0.2.0 → 0.4.0

package/src/extension-runtime.ts

@@ -6,6 +6,7 @@ import type {
 	SessionBeforeCompactEvent,
 } from "@earendil-works/pi-coding-agent";
 import { executeNativeCompaction } from "./compact-client";
+import { executeV2Compaction } from "./compact-client-v2";
 import { loadExtensionConfig } from "./config";
 import { writeDebugArtifact } from "./debug";
 import { resolveLatestNativeCompactionEntry } from "./details-store";
@@ -15,6 +16,7 @@ import {
 	serializeLiveTailToResponsesInput,
 } from "./payload-rewrite";
 import { getCompactionRequestExtras, rememberRequestContext } from "./request-context-cache";
+import { buildRetainedMessages } from "./retained-messages";
 import {
 	isResponsesCompatiblePayload,
 	resolveNativeCompactionEnvironment,
@@ -26,6 +28,8 @@ import {
 	createNativeCompactionResult,
 	EXTENSION_ID,
 	isNativeCompactionDetails,
+	NATIVE_COMPACTION_STRATEGY,
+	NATIVE_COMPACTION_STRATEGY_V2,
 	type ExtensionConfig,
 	type NativeCompactionDetails,
 	type NativeCompactionRequestMeta,
@@ -90,7 +94,7 @@ function buildCompactionInstructions(systemPrompt: string, customInstructions?:
 	return `${systemPrompt}\n\nAdditional user guidance for this manual /compact request:\n${guidance}`;
 }
 
-async function runResponsesNativeCompact(
+async function runResponsesV1Compact(
 	event: SessionBeforeCompactEvent,
 	ctx: ExtensionContext,
 	config: ExtensionConfig,
@@ -105,7 +109,7 @@ async function runResponsesNativeCompact(
 		baseUrl: runtime.baseUrl,
 	});
 
-	let requestSource: "session-context" | "latest-native-replay";
+	let requestSource: "session-context" | "non-native-session-context" | "latest-native-replay";
 	let request: NativeCompactionRequestBody;
 	if (latestNativeCompaction.ok) {
 		const liveTailEntries = branchEntries.slice(latestNativeCompaction.index + 1);
@@ -119,8 +123,13 @@ async function runResponsesNativeCompact(
 			input,
 			instructions,
 		};
-	} else if (latestNativeCompaction.reason === "no-compaction") {
-		requestSource = "session-context";
+	} else if (
+		latestNativeCompaction.reason === "no-compaction" ||
+		(latestNativeCompaction.reason === "latest-compaction-not-native" &&
+			config.allowCompactionContinuityBreak)
+	) {
+		requestSource =
+			latestNativeCompaction.reason === "no-compaction" ? "session-context" : "non-native-session-context";
 		request = serializeMessagesToCompactRequest({
 			model: runtime.currentModel,
 			messages: ctx.sessionManager.buildSessionContext().messages,
@@ -130,7 +139,7 @@ async function runResponsesNativeCompact(
 		writeDebugArtifact(
 			"compaction-event",
 			{
-				event: "session_before_compact.responses-compact-skip",
+				event: "session_before_compact.v1-compact-skip",
 				reason: latestNativeCompaction.reason,
 				provider: runtime.provider,
 				api: runtime.api,
@@ -164,7 +173,7 @@ async function runResponsesNativeCompact(
 		writeDebugArtifact(
 			"compaction-event",
 			{
-				event: "session_before_compact.responses-compact-failure",
+				event: "session_before_compact.v1-compact-failure",
 				reason: compactResult.reason,
 				status: compactResult.status,
 				errorMessage: compactResult.errorMessage,
@@ -191,7 +200,7 @@ async function runResponsesNativeCompact(
 		writeDebugArtifact(
 			"compaction-event",
 			{
-				event: "session_before_compact.invalid-native-details",
+				event: "session_before_compact.v1-invalid-native-details",
 				reason: error instanceof Error ? error.message : String(error),
 				provider: runtime.provider,
 				api: runtime.api,
@@ -214,7 +223,7 @@ async function runResponsesNativeCompact(
 	writeDebugArtifact(
 		"compaction-event",
 		{
-			event: "session_before_compact.responses-compact-success",
+			event: "session_before_compact.v1-compact-success",
 			provider: runtime.provider,
 			api: runtime.api,
 			model: runtime.model,
@@ -233,6 +242,164 @@ async function runResponsesNativeCompact(
 	return { outcome: "success", compaction };
 }
 
+/**
+ * V2 compaction: stream a Responses request with compaction_trigger appended.
+ * On success, returns retained messages + encrypted compaction blob.
+ */
+async function runResponsesV2Compact(
+	event: SessionBeforeCompactEvent,
+	ctx: ExtensionContext,
+	config: ExtensionConfig,
+	runtime: NativeCompactionRuntime,
+): Promise<ResponsesCompactOutcome> {
+	const instructions = buildCompactionInstructions(ctx.getSystemPrompt(), event.customInstructions);
+	const branchEntries = ctx.sessionManager.getBranch();
+	const latestNativeCompaction = resolveLatestNativeCompactionEntry(branchEntries, {
+		provider: runtime.provider,
+		api: runtime.api,
+		model: runtime.model,
+		baseUrl: runtime.baseUrl,
+	});
+
+	let requestSource: "session-context" | "non-native-session-context" | "latest-native-replay";
+	let request: NativeCompactionRequestBody;
+	if (latestNativeCompaction.ok) {
+		const liveTailEntries = branchEntries.slice(latestNativeCompaction.index + 1);
+		requestSource = "latest-native-replay";
+		const input: ResponsesInputItem[] = [
+			...(cloneOpaqueWindow(latestNativeCompaction.entry.details.compactedWindow) as ResponsesInputItem[]),
+			...serializeLiveTailToResponsesInput({ model: runtime.currentModel, entries: liveTailEntries }),
+		];
+		request = {
+			model: runtime.currentModel.id,
+			input,
+			instructions,
+		};
+	} else if (
+		latestNativeCompaction.reason === "no-compaction" ||
+		(latestNativeCompaction.reason === "latest-compaction-not-native" &&
+			config.allowCompactionContinuityBreak)
+	) {
+		requestSource =
+			latestNativeCompaction.reason === "no-compaction" ? "session-context" : "non-native-session-context";
+		request = serializeMessagesToCompactRequest({
+			model: runtime.currentModel,
+			messages: ctx.sessionManager.buildSessionContext().messages,
+			instructions,
+		});
+	} else {
+		writeDebugArtifact(
+			"compaction-event",
+			{
+				event: "session_before_compact.v2-compact-skip",
+				reason: latestNativeCompaction.reason,
+				provider: runtime.provider,
+				api: runtime.api,
+				model: runtime.model,
+				baseUrl: runtime.baseUrl,
+				latestCompactionIndex: latestNativeCompaction.latestCompactionIndex,
+				latestCompactionIdentity: getCompactionIdentityDebugInfo(latestNativeCompaction.latestCompaction),
+			},
+			config,
+			ctx,
+		);
+		return { outcome: "failed" };
+	}
+
+	const extras = getCompactionRequestExtras(runtime.model, getSessionId(ctx));
+	if (extras) {
+		request = { ...request, ...extras };
+	}
+
+	const v2Result = await executeV2Compaction({
+		runtime,
+		request,
+		signal: event.signal,
+		settings: config,
+		context: ctx,
+	});
+
+	if (!v2Result.ok) {
+		writeDebugArtifact(
+			"compaction-event",
+			{
+				event: "session_before_compact.v2-compact-failure",
+				reason: v2Result.reason,
+				status: v2Result.status,
+				errorMessage: v2Result.errorMessage,
+			},
+			config,
+			ctx,
+		);
+		return v2Result.reason === "aborted" ? { outcome: "aborted" } : { outcome: "failed" };
+	}
+
+	// Build compacted window: retained messages + compaction blob.
+	const retainedMessages = buildRetainedMessages(request.input);
+	const compactedWindow = [...retainedMessages, v2Result.compactionItem];
+
+	let details: NativeCompactionDetails;
+	try {
+		details = createNativeCompactionDetails(
+			{
+				provider: runtime.provider,
+				api: runtime.api,
+				model: runtime.model,
+				baseUrl: runtime.baseUrl,
+				compactedWindow,
+				compactResponseId: v2Result.responseId,
+				createdAt: v2Result.createdAt,
+				requestMeta: buildCompactionRequestMeta(event),
+			},
+			NATIVE_COMPACTION_STRATEGY_V2,
+		);
+	} catch (error) {
+		writeDebugArtifact(
+			"compaction-event",
+			{
+				event: "session_before_compact.v2-invalid-native-details",
+				reason: error instanceof Error ? error.message : String(error),
+				provider: runtime.provider,
+				api: runtime.api,
+				model: runtime.model,
+				baseUrl: runtime.baseUrl,
+			},
+			config,
+			ctx,
+		);
+		return { outcome: "failed" };
+	}
+
+	// V2 blob is encrypted; no summary text can be extracted.
+	const compaction = createNativeCompactionResult({
+		firstKeptEntryId: event.preparation.firstKeptEntryId,
+		tokensBefore: event.preparation.tokensBefore,
+		details,
+	});
+
+	writeDebugArtifact(
+		"compaction-event",
+		{
+			event: "session_before_compact.v2-compact-success",
+			provider: runtime.provider,
+			api: runtime.api,
+			model: runtime.model,
+			requestSource,
+			requestInputItems: request.input.length,
+			requestExtras: extras ? Object.keys(extras) : [],
+			compactResponseId: v2Result.responseId,
+			retainedMessageCount: retainedMessages.length,
+			compactedItems: compactedWindow.length,
+			usage: v2Result.usage,
+			firstKeptEntryId: event.preparation.firstKeptEntryId,
+		},
+		config,
+		ctx,
+	);
+
+	return { outcome: "success", compaction };
+}
+
 async function handleSessionBeforeCompact(event: SessionBeforeCompactEvent, ctx: ExtensionContext) {
 	const { config } = loadExtensionConfig();
 	if (!config.enabled) {
@@ -266,7 +433,14 @@ async function handleSessionBeforeCompact(event: SessionBeforeCompactEvent, ctx:
 		responsesCompactApis: config.responsesCompactApis,
 	});
 	if (resolution.ok) {
-		const responsesOutcome = await runResponsesNativeCompact(event, ctx, config, resolution.runtime);
+		let responsesOutcome: ResponsesCompactOutcome;
+
+		if (config.compactionVersion === "v2") {
+			responsesOutcome = await runResponsesV2Compact(event, ctx, config, resolution.runtime);
+		} else {
+			responsesOutcome = await runResponsesV1Compact(event, ctx, config, resolution.runtime);
+		}
+
 		if (responsesOutcome.outcome === "success") {
 			return { compaction: responsesOutcome.compaction };
 		}
@@ -291,7 +465,7 @@ async function handleSessionBeforeCompact(event: SessionBeforeCompactEvent, ctx:
 	}
 
 	// Branch 2: run pi's native compaction method with the configured model.
-	const fallback = await runNativeFallbackCompaction({ ctx, event, config });
+	const fallback = await runNativeFallbackCompaction({ ctx, event, config, sessionId: getSessionId(ctx) });
 	if (fallback.ok) {
 		if (ctx.hasUI) {
 			ctx.ui.notify(
@@ -304,6 +478,7 @@ async function handleSessionBeforeCompact(event: SessionBeforeCompactEvent, ctx:
 			{
 				event: "session_before_compact.fallback-success",
 				model: fallback.model,
+				usage: fallback.usage,
 			},
 			config,
 			ctx,
@@ -496,4 +671,23 @@ export default function (pi: ExtensionAPI) {
 
 	pi.on("session_before_compact", handleSessionBeforeCompact);
 	pi.on("before_provider_request", handleBeforeProviderRequest);
+
+	pi.on("session_compact_failed", (event, ctx) => {
+		const { config } = loadExtensionConfig();
+		if (!config.enabled) return;
+
+		writeDebugArtifact(
+			"compaction-event",
+			{
+				event: "session_compact_failed",
+				reason: event.reason,
+				errorMessage: event.errorMessage,
+				aborted: event.aborted,
+				willRetry: event.willRetry,
+				fromExtension: event.fromExtension,
+			},
+			config,
+			ctx,
+		);
+	});
 }

package/src/native-fallback.ts

@@ -26,6 +26,7 @@ export type NativeFallbackResult =
 			ok: true;
 			result: CompactionResult;
 			model: { provider: string; id: string };
+			usage?: CompactionResult["usage"];
 	  }
 	| {
 			ok: false;
@@ -38,9 +39,21 @@ export type NativeFallbackResult =
 export type NativeCompactFn = typeof compact;
 
 type ResolvedAuth =
-	| { ok: true; apiKey?: string; headers?: Record<string, string>; env?: Record<string, string> }
+	| { ok: true; apiKey?: string; headers?: Record<string, string | null>; env?: Record<string, string> }
 	| { ok: false; error: string };
 
+/** Strip null-valued entries so downstream consumers receive a clean Record<string, string>. */
+function filterNullHeaders(headers: Record<string, string | null> | undefined): Record<string, string> | undefined {
+	if (!headers) return undefined;
+	const filtered: Record<string, string> = {};
+	for (const [key, value] of Object.entries(headers)) {
+		if (value !== null) {
+			filtered[key] = value;
+		}
+	}
+	return Object.keys(filtered).length > 0 ? filtered : undefined;
+}
+
 /** Parse "provider/model-id" (model ids may themselves contain slashes). */
 export function parseModelSpec(spec: string): ParsedModelSpec | undefined {
 	const trimmed = spec.trim();
@@ -82,6 +95,7 @@ export async function runNativeFallbackCompaction(args: {
 	event: SessionBeforeCompactEvent;
 	config: ExtensionConfig;
 	compactFn?: NativeCompactFn;
+	sessionId?: string;
 }): Promise<NativeFallbackResult> {
 	const { ctx, event, config } = args;
 	const compactFn = args.compactFn ?? compact;
@@ -120,12 +134,15 @@ export async function runNativeFallbackCompaction(args: {
 			event.preparation,
 			model,
 			auth.apiKey,
-			auth.headers,
+			filterNullHeaders(auth.headers),
 			event.customInstructions,
 			event.signal,
 			config.compactionThinkingLevel,
-			undefined,
+			undefined, // streamFn
 			auth.env,
+			undefined, // retry (use pi defaults)
+			undefined, // callbacks
+			args.sessionId,
 		);
 
 		if (event.signal.aborted) {
@@ -139,6 +156,7 @@ export async function runNativeFallbackCompaction(args: {
 			ok: true,
 			result,
 			model: { provider: model.provider, id: model.id },
+			usage: result.usage,
 		};
 	} catch (error) {
 		if (event.signal.aborted || isAbortError(error)) {

package/src/retained-messages.ts

@@ -0,0 +1,98 @@
+/**
+ * V2 compaction retained-message filtering.
+ *
+ * After the API returns an encrypted compaction blob, V2 keeps a window of recent
+ * user/developer/system messages alongside the blob so the model retains explicit
+ * user instructions and context anchors. This module mirrors the filtering and
+ * budget logic from codex-rs `compact_remote_v2.rs`.
+ */
+
+/** Token budget for retained messages (matches codex-rs RETAINED_MESSAGE_TOKEN_BUDGET). */
+export const RETAINED_MESSAGE_TOKEN_BUDGET = 65_536;
+
+/** Messages larger than this are excluded even if they are of a retained role. */
+const MAX_SINGLE_ITEM_TOKENS = 10_000;
+
+/** Rough chars-per-token ratio for budget estimation. */
+const CHARS_PER_TOKEN = 4;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Estimate the token count of an opaque input item by serializing to JSON and
+ * dividing by the chars-per-token ratio. This is intentionally rough — codex-rs
+ * uses a real tokenizer but we don't have one in the extension runtime.
+ */
+export function estimateItemTokens(item: unknown): number {
+	try {
+		const length = JSON.stringify(item).length;
+		return Math.ceil(length / CHARS_PER_TOKEN);
+	} catch {
+		return 0;
+	}
+}
+
+/**
+ * Whether an input item should be retained alongside the compaction blob.
+ *
+ * Retained roles (matching codex-rs `is_retained_for_remote_compaction_v2`):
+ * - `user` messages
+ * - `developer` messages
+ * - `system` messages
+ *
+ * Everything else (assistant, function_call, function_call_output, reasoning,
+ * compaction, etc.) is excluded.
+ */
+export function isRetainedItem(item: unknown): boolean {
+	if (!isRecord(item)) {
+		return false;
+	}
+
+	const role = item.role;
+	if (typeof role === "string") {
+		return role === "user" || role === "developer" || role === "system";
+	}
+
+	return false;
+}
+
+/**
+ * From a list of Responses API input items, select the most recent retained
+ * messages that fit within the token budget. Items are selected newest-first
+ * (reverse order) and returned in their original chronological order.
+ *
+ * Oversized individual items (> MAX_SINGLE_ITEM_TOKENS) are skipped.
+ */
+export function buildRetainedMessages(
+	input: readonly unknown[],
+	budget: number = RETAINED_MESSAGE_TOKEN_BUDGET,
+): unknown[] {
+	// Filter to retained roles first.
+	const retained: Array<{ index: number; item: unknown; tokens: number }> = [];
+	for (let i = 0; i < input.length; i++) {
+		const item = input[i];
+		if (!isRetainedItem(item)) continue;
+
+		const tokens = estimateItemTokens(item);
+		if (tokens > MAX_SINGLE_ITEM_TOKENS) continue;
+
+		retained.push({ index: i, item, tokens });
+	}
+
+	// Select from newest to oldest within the budget.
+	let remaining = budget;
+	const selected: typeof retained = [];
+
+	for (let i = retained.length - 1; i >= 0; i--) {
+		const entry = retained[i]!;
+		if (entry.tokens > remaining) break;
+		remaining -= entry.tokens;
+		selected.push(entry);
+	}
+
+	// Return in original chronological order.
+	selected.reverse();
+	return selected.map((entry) => structuredClone(entry.item));
+}

package/src/runtime.ts

@@ -4,6 +4,8 @@ import { RESPONSES_COMPACT_CAPABLE_APIS } from "./types";
 
 const OPENAI_COMPACT_PATH = "responses/compact";
 const CODEX_COMPACT_PATH = "codex/responses/compact";
+const OPENAI_RESPONSES_PATH = "responses";
+const CODEX_RESPONSES_PATH = "codex/responses";
 
 type ResponsesCompactApi = (typeof RESPONSES_COMPACT_CAPABLE_APIS)[number];
 
@@ -40,6 +42,7 @@ export type NativeCompactionRuntime = {
 	headers?: Record<string, string>;
 	compactPath: string;
 	compactUrl: string;
+	responsesUrl: string;
 	payload?: ResponsesCompatibleRequestPayload;
 	currentModel: RuntimeModel;
 };
@@ -74,6 +77,29 @@ export function normalizeBaseUrl(baseUrl: string | undefined | null): string | u
 	return normalized ? normalized : undefined;
 }
 
+function buildOpenAIResponsesUrl(baseUrl: string): string {
+	const normalized = normalizeBaseUrl(baseUrl) ?? baseUrl;
+	if (normalized.endsWith("/responses")) {
+		return normalized;
+	}
+	return `${normalized}/${OPENAI_RESPONSES_PATH}`;
+}
+
+function buildCodexResponsesUrl(baseUrl: string): string {
+	const normalized = normalizeBaseUrl(baseUrl) ?? baseUrl;
+	if (normalized.endsWith("/codex/responses")) {
+		return normalized;
+	}
+	if (normalized.endsWith("/codex")) {
+		return `${normalized}/responses`;
+	}
+	return `${normalized}/${CODEX_RESPONSES_PATH}`;
+}
+
+export function buildResponsesUrl(baseUrl: string, api: ResponsesCompactApi): string {
+	return api === "openai-codex-responses" ? buildCodexResponsesUrl(baseUrl) : buildOpenAIResponsesUrl(baseUrl);
+}
+
 function buildOpenAICompactUrl(baseUrl: string): string {
 	const normalized = normalizeBaseUrl(baseUrl) ?? baseUrl;
 	if (normalized.endsWith("/responses")) {
@@ -101,13 +127,25 @@ export function buildCompactPath(api: ResponsesCompactApi): string {
 	return api === "openai-codex-responses" ? CODEX_COMPACT_PATH : OPENAI_COMPACT_PATH;
 }
 
+/** Strip null-valued entries so downstream consumers receive a clean Record<string, string>. */
+function filterNullHeaders(headers: Record<string, string | null> | undefined): Record<string, string> | undefined {
+	if (!headers) return undefined;
+	const filtered: Record<string, string> = {};
+	for (const [key, value] of Object.entries(headers)) {
+		if (value !== null) {
+			filtered[key] = value;
+		}
+	}
+	return Object.keys(filtered).length > 0 ? filtered : undefined;
+}
+
 async function resolveRequestAuth(
 	ctx: ExtensionContext,
 	model: RuntimeModel,
 ): Promise<{ apiKey?: string; headers?: Record<string, string> }> {
 	const modelRegistry = ctx.modelRegistry as {
 		getApiKeyAndHeaders?: (currentModel: RuntimeModel) => Promise<
-			| { ok: true; apiKey?: string; headers?: Record<string, string> }
+			| { ok: true; apiKey?: string; headers?: Record<string, string | null> }
 			| { ok: false; error: string }
 		>;
 	};
@@ -117,7 +155,7 @@ async function resolveRequestAuth(
 	}
 
 	const auth = await modelRegistry.getApiKeyAndHeaders(model);
-	return auth.ok ? { apiKey: auth.apiKey, headers: auth.headers } : {};
+	return auth.ok ? { apiKey: auth.apiKey, headers: filterNullHeaders(auth.headers) } : {};
 }
 
 export function isSupportedApi(api: string): api is ResponsesCompactApi {
@@ -234,6 +272,7 @@ export async function resolveNativeCompactionEnvironment(
 			headers,
 			compactPath: buildCompactPath(descriptor.api),
 			compactUrl: buildCompactUrl(descriptor.baseUrl, descriptor.api),
+			responsesUrl: buildResponsesUrl(descriptor.baseUrl, descriptor.api),
 			payload: requestPayload,
 			currentModel,
 		},

package/src/shared-headers.ts

@@ -0,0 +1,103 @@
+/**
+ * Shared HTTP header construction for V1 and V2 compaction clients.
+ *
+ * Extracts the header building logic that was previously private in
+ * compact-client.ts so both compact-client.ts and compact-client-v2.ts
+ * can share it without duplication.
+ */
+
+import type { NativeCompactionRuntime } from "./runtime";
+
+const JSON_CONTENT_TYPE = "application/json";
+
+function decodeJwtPayload(token: string): Record<string, unknown> | undefined {
+	const parts = token.split(".");
+	if (parts.length !== 3) {
+		return undefined;
+	}
+
+	try {
+		const payloadText = Buffer.from(parts[1]!, "base64url").toString("utf8");
+		const payload = JSON.parse(payloadText);
+		return payload && typeof payload === "object" && !Array.isArray(payload)
+			? (payload as Record<string, unknown>)
+			: undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function extractCodexAccountId(token: string): string | undefined {
+	const payload = decodeJwtPayload(token);
+	const authClaims = payload?.["https://api.openai.com/auth"];
+	if (!isRecord(authClaims)) {
+		return undefined;
+	}
+
+	const accountId = authClaims.chatgpt_account_id;
+	return typeof accountId === "string" && accountId.trim().length > 0 ? 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})`;
+}
+
+/**
+ * Build HTTP headers for a compaction request from the resolved runtime.
+ *
+ * Handles model-level headers, extension-resolved headers, authorization,
+ * and Codex-specific headers (account ID, originator, user-agent, beta flag).
+ *
+ * @param accept - The Accept header value. Defaults to `application/json`.
+ */
+export function toHeaders(
+	runtime: NativeCompactionRuntime,
+	accept: string = JSON_CONTENT_TYPE,
+): Record<string, string> {
+	const headers = new Headers();
+	// Model-level headers may contain null values (ProviderHeaders); null means "unset".
+	for (const [key, value] of Object.entries(runtime.currentModel.headers ?? {})) {
+		if (value != null) {
+			headers.set(key, String(value));
+		}
+	}
+	// Extension-resolved headers (already filtered by resolveRequestAuth, but defensive).
+	for (const [key, value] of Object.entries(runtime.headers ?? {})) {
+		if (value == null) {
+			headers.delete(key);
+		} else {
+			headers.set(key, value);
+		}
+	}
+	headers.set("accept", accept);
+	headers.set("content-type", JSON_CONTENT_TYPE);
+	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");
+	}
+
+	return Object.fromEntries(headers.entries());
+}
+
+/** Check whether an error represents an intentional abort (AbortController / AbortSignal). */
+export function isAbortError(error: unknown): boolean {
+	return (
+		(error instanceof DOMException && error.name === "AbortError") ||
+		(error instanceof Error && (error.name === "AbortError" || error.name === "ABORT_ERR"))
+	);
+}