@gajae-code/agent-core 0.5.2 → 0.5.4

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [0.5.4] - 2026-06-17
+
+### Fixed
+
+- Maintenance one-shot LLM calls now preserve active provider session state and the configured WebSocket transport preference. `SummaryOptions`, `HandoffOptions`, and `GenerateBranchSummaryOptions` accept `sessionId`, `providerSessionState`, and `preferWebsockets`, and `generateSummary`, `generateShortSummary`, `generateTurnPrefixSummary`, `generateHandoff`, `generateBranchSummary`, and `compact()` forward them through to `completeSimple` — previously these fields were dropped, so Codex/OpenAI-compatible compaction summaries, handoff generation, and branch summaries fell back to HTTP/SSE and lost `session_id` affinity even with `providers.openaiWebsockets: "on"`. Split-turn compaction now runs its history and turn-prefix summaries sequentially when they share a single provider WebSocket session, avoiding `websocket request already in progress`; non-WebSocket sessions still run them in parallel. `Agent` exposes a `preferWebsockets` getter so callers can forward the live transport preference (#736).
+
+## [0.5.3] - 2026-06-16
+
+### Fixed
+
+- Bounded agent context growth, compaction, and token accounting for long-running sessions: `appendMessage` pushes in place instead of rebuilding the array; the append-only context keeps rolling per-message hashes instead of rescanning the full digest; an emergency-compaction floor that cannot be disabled now surfaces its reason; `getSessionStats` is single-pass; and `nativeCountTokens` skips the synchronous ~39 MB BPE tokenizer above a 2 MiB input cap, falling back to the cheap heuristic (#717).
+
 ## [0.5.2] - 2026-06-15
 
 ### Fixed

package/dist/types/agent.d.ts

@@ -193,6 +193,12 @@ export declare class Agent {
     set sessionId(value: string | undefined);
     get providerSessionId(): string | undefined;
     set providerSessionId(value: string | undefined);
+    /**
+     * Whether websocket transport is preferred when the provider implementation
+     * supports it. Read by maintenance one-shot calls (compaction, handoff,
+     * branch summary) so they forward the same transport preference as live turns.
+     */
+    get preferWebsockets(): boolean | undefined;
     /**
      * Static metadata forwarded to every API request when no resolver is installed
      * (e.g. `metadata.user_id` for Anthropic session attribution). Setting this

package/dist/types/compaction/branch-summarization.d.ts

@@ -4,7 +4,7 @@
  * When navigating to a different point in the session tree, this generates
  * a summary of the branch being left so context isn't lost.
  */
-import type { Model } from "@gajae-code/ai";
+import type { Model, ProviderSessionState } from "@gajae-code/ai";
 import { type AgentTelemetry } from "../telemetry";
 import type { AgentMessage } from "../types";
 import type { ReadonlySessionManager, SessionEntry } from "./entries";
@@ -57,6 +57,15 @@ export interface GenerateBranchSummaryOptions {
      * wrapped in an OTEL chat span tagged with `pi.gen_ai.oneshot.kind = "branch_summary"`.
      */
     telemetry?: AgentTelemetry;
+    /**
+     * Provider session affinity id forwarded to the branch summary LLM call so it
+     * reuses the live turn's provider/WebSocket session.
+     */
+    sessionId?: string;
+    /** Shared provider state map so the branch summary call reuses session-scoped transport/session caches. */
+    providerSessionState?: Map<string, ProviderSessionState>;
+    /** Hint that websocket transport should be preferred when supported by the provider implementation. */
+    preferWebsockets?: boolean;
 }
 /**
  * Collect entries that should be summarized when navigating from one position to another.

package/dist/types/compaction/compaction.d.ts

@@ -4,7 +4,7 @@
  * Pure functions for compaction logic. The session manager handles I/O,
  * and after compaction the session is reloaded.
  */
-import { type MessageAttribution, type Model, type Usage } from "@gajae-code/ai";
+import { type MessageAttribution, type Model, type ProviderSessionState, type Usage } from "@gajae-code/ai";
 import { type AgentTelemetry } from "../telemetry";
 import type { AgentMessage, AgentTool } from "../types";
 import type { SessionEntry } from "./entries";
@@ -66,6 +66,37 @@ export declare function effectiveReserveTokens(contextWindow: number, settings:
  * the safe input budget so prompt + reserved output cannot exceed the total window.
  */
 export declare function shouldCompact(contextTokens: number, contextWindow: number, settings: CompactionSettings, maxOutputTokens?: number): boolean;
+/** Reason a compaction was triggered. `token` is the normal user-configurable path; the rest are emergency floors. */
+export type CompactionTriggerReason = "token" | "heap" | "providerBytes" | "messageCount" | "imageBytes";
+/** A point-in-time resource sample. Supplied by an injectable sampler so tests never read real RSS. */
+export interface EmergencyCompactionSample {
+    /** Resident heap bytes (e.g. process.memoryUsage().heapUsed). */
+    heapUsedBytes: number;
+    /** Approximate serialized provider-context bytes. */
+    providerBytes: number;
+    /** Provider-visible message count. */
+    messageCount: number;
+    /** Approximate inline image bytes in the provider context. */
+    imageBytes: number;
+}
+export interface EmergencyCompactionLimits {
+    heapUsedBytes: number;
+    providerBytes: number;
+    messageCount: number;
+    imageBytes: number;
+}
+/**
+ * Non-disableable emergency floors. These sit well above normal usage and exist so a
+ * long session on weak hardware compacts before OOM even when token-based compaction is
+ * disabled or its threshold is set too high. They are NOT user-tunable down to zero.
+ */
+export declare const DEFAULT_EMERGENCY_COMPACTION_LIMITS: EmergencyCompactionLimits;
+/**
+ * Returns the first emergency limit exceeded (heap > providerBytes > imageBytes > messageCount),
+ * or null when none is. Pure and sampler-injected; the caller routes the result through the
+ * normal pair-safe `compact()` cut logic so a tool_use/tool_result pair is never split.
+ */
+export declare function emergencyCompactionReason(sample: EmergencyCompactionSample, limits?: EmergencyCompactionLimits): CompactionTriggerReason | null;
 export declare function resolveThresholdTokens(contextWindow: number, settings: CompactionSettings, maxOutputTokens?: number): number;
 /**
  * Estimate token count for a message using the native o200k tokenizer.
@@ -151,6 +182,16 @@ export interface SummaryOptions {
      */
     telemetry?: AgentTelemetry;
     authCredentialType?: "api_key" | "oauth";
+    /**
+     * Provider session affinity id forwarded to the maintenance LLM call so it
+     * reuses the live turn's provider/WebSocket session (matches the
+     * `providerSessionId ?? sessionId` the agent loop sends for normal turns).
+     */
+    sessionId?: string;
+    /** Shared provider state map so maintenance calls reuse session-scoped transport/session caches. */
+    providerSessionState?: Map<string, ProviderSessionState>;
+    /** Hint that websocket transport should be preferred when supported by the provider implementation. */
+    preferWebsockets?: boolean;
 }
 export declare function generateSummary(currentMessages: AgentMessage[], model: Model, reserveTokens: number, apiKey: string, signal?: AbortSignal, customInstructions?: string, previousSummary?: string, options?: SummaryOptions): Promise<string>;
 export interface HandoffOptions {
@@ -168,6 +209,15 @@ export interface HandoffOptions {
      */
     telemetry?: AgentTelemetry;
     authCredentialType?: "api_key" | "oauth";
+    /**
+     * Provider session affinity id forwarded to the handoff LLM call so it
+     * reuses the live turn's provider/WebSocket session.
+     */
+    sessionId?: string;
+    /** Shared provider state map so the handoff call reuses session-scoped transport/session caches. */
+    providerSessionState?: Map<string, ProviderSessionState>;
+    /** Hint that websocket transport should be preferred when supported by the provider implementation. */
+    preferWebsockets?: boolean;
 }
 export declare function renderHandoffPrompt(customInstructions?: string): string;
 export declare function generateHandoff(messages: AgentMessage[], model: Model, apiKey: string, options: HandoffOptions, signal?: AbortSignal): Promise<string>;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/agent-core",
-	"version": "0.5.2",
+	"version": "0.5.4",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://gaebal-gajae.dev",
 	"author": "Yeachan-Heo",
@@ -35,9 +35,9 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/ai": "0.5.2",
-		"@gajae-code/natives": "0.5.2",
-		"@gajae-code/utils": "0.5.2",
+		"@gajae-code/ai": "0.5.4",
+		"@gajae-code/natives": "0.5.4",
+		"@gajae-code/utils": "0.5.4",
 		"@opentelemetry/api": "^1.9.0"
 	},
 	"devDependencies": {

package/src/agent.ts

@@ -408,6 +408,15 @@ export class Agent {
 		this.#providerSessionId = value;
 	}
 
+	/**
+	 * Whether websocket transport is preferred when the provider implementation
+	 * supports it. Read by maintenance one-shot calls (compaction, handoff,
+	 * branch summary) so they forward the same transport preference as live turns.
+	 */
+	get preferWebsockets(): boolean | undefined {
+		return this.#preferWebsockets;
+	}
+
 	/**
 	 * Static metadata forwarded to every API request when no resolver is installed
 	 * (e.g. `metadata.user_id` for Anthropic session attribution). Setting this
@@ -827,7 +836,10 @@ export class Agent {
 	}
 
 	appendMessage(m: AgentMessage) {
-		this.#state.messages = [...this.#state.messages, m];
+		// In-place push (not [...messages, m]): appending M messages over a session of
+		// N is O(N+M), not O(M*N). Consumers read state.messages fresh; run() snapshots
+		// via slice() at the API boundary, so no caller relies on per-append array identity.
+		this.#state.messages.push(m);
 	}
 
 	popMessage(): AgentMessage | undefined {

package/src/append-only-context.ts

@@ -199,8 +199,8 @@ export class AppendOnlyContextManager {
 	readonly log = new AppendOnlyLog();
 	/** How many normalized messages were synced into the log as of the last sync. */
 	#lastSyncCount = 0;
-	/** Fingerprint plus source bytes of synced message content — detects in-place rewrites with no hash-only equality. */
-	#syncedDigest = emptyMessageDigest();
+	/** Per-synced-message content hashes (rolling digest). Detects in-place rewrites without retaining a full serialized-history string. */
+	#syncedHashes: (number | bigint)[] = [];
 	/** Number of provider-normalized messages that were seeded before child-local messages. */
 	#seededPrefixCount = 0;
 
@@ -236,35 +236,41 @@ export class AppendOnlyContextManager {
 		const includesSeedPrefix =
 			seededPrefixLength > 0 &&
 			normalizedMessages.length >= seededPrefixLength &&
-			this.#computeDigestRange(normalizedMessages, 0, seededPrefixLength).source ===
-				this.#computeDigestRange(this.log.entries(), 0, seededPrefixLength).source;
+			this.#rangeHashesEqual(normalizedMessages, this.log.entries(), seededPrefixLength);
 		const messagesToSync =
 			seededPrefixLength > 0 && !includesSeedPrefix
 				? [...this.log.entries().slice(0, seededPrefixLength), ...normalizedMessages]
 				: normalizedMessages;
 
-		// Detect in-place rewrites of already-synced messages.
+		// Detect in-place rewrites of already-synced messages via per-message content
+		// hashes (no retained full serialized-history string; F5).
 		if (
 			this.#lastSyncCount > 0 &&
 			this.#lastSyncCount <= messagesToSync.length &&
-			this.#computeDigestRange(messagesToSync, 0, this.#lastSyncCount).source !== this.#syncedDigest.source
+			this.#prefixChanged(messagesToSync, this.#lastSyncCount)
 		) {
 			if (this.#seededPrefixCount > 0) {
-				throw new Error("AppendOnlyContextManager.syncMessages() seed prefix changed");
+				// F9: a seeded fork whose inherited prefix changed (e.g. after compaction)
+				// rebases onto the new provider context instead of throwing.
+				this.#rebaseToBaseline(normalizedMessages);
+				return;
 			}
 			this.log.clear();
 			this.#lastSyncCount = 0;
+			this.#syncedHashes = [];
 		}
 
-		// Compaction — array shrunk. Seeded forks preserve the inherited prefix
-		// and append child-local deltas, so a shorter child message array is not a
-		// compaction signal while a seed prefix is active.
+		// Compaction — array shrunk. Seeded forks preserve the inherited prefix and
+		// append child-local deltas, so a shorter child array is not a compaction signal
+		// while a seed prefix is active; a genuine seeded compaction rebases (F9).
 		if (messagesToSync.length < this.#lastSyncCount) {
 			if (this.#seededPrefixCount > 0) {
-				throw new Error("AppendOnlyContextManager.syncMessages() cannot compact a seeded fork without reset");
+				this.#rebaseToBaseline(normalizedMessages);
+				return;
 			}
 			this.log.clear();
 			this.#lastSyncCount = 0;
+			this.#syncedHashes = [];
 		}
 
 		const newMsgs = messagesToSync.slice(this.#lastSyncCount);
@@ -273,7 +279,7 @@ export class AppendOnlyContextManager {
 		}
 
 		this.#lastSyncCount = messagesToSync.length;
-		this.#syncedDigest = this.#computeDigest(messagesToSync);
+		this.#syncedHashes = this.#hashRange(messagesToSync, 0, messagesToSync.length);
 	}
 
 	seedNormalizedMessages(messages: readonly Message[], options?: { reset?: boolean }): void {
@@ -284,7 +290,7 @@ export class AppendOnlyContextManager {
 		this.log.clear();
 		this.log.extend(clonedMessages);
 		this.#lastSyncCount = clonedMessages.length;
-		this.#syncedDigest = this.#computeDigest(clonedMessages);
+		this.#syncedHashes = this.#hashRange(clonedMessages, 0, clonedMessages.length);
 		this.#seededPrefixCount = clonedMessages.length;
 	}
 
@@ -293,7 +299,7 @@ export class AppendOnlyContextManager {
 		this.prefix.invalidate();
 		this.log.clear();
 		this.#lastSyncCount = 0;
-		this.#syncedDigest = emptyMessageDigest();
+		this.#syncedHashes = [];
 		this.#seededPrefixCount = 0;
 	}
 
@@ -301,7 +307,7 @@ export class AppendOnlyContextManager {
 	resetSyncCursor(): void {
 		this.log.clear();
 		this.#lastSyncCount = 0;
-		this.#syncedDigest = emptyMessageDigest();
+		this.#syncedHashes = [];
 		this.#seededPrefixCount = 0;
 	}
 
@@ -321,28 +327,45 @@ export class AppendOnlyContextManager {
 		this.prefix.invalidate();
 		this.log.clear();
 		this.#lastSyncCount = 0;
-		this.#syncedDigest = emptyMessageDigest();
+		this.#syncedHashes = [];
 		this.#seededPrefixCount = 0;
 		this.prefix.build(context, options);
 	}
 
-	/**
-	 * Deterministic digest over the provider-visible message payload. The source
-	 * string is kept and compared for equality so the hash is only a fast summary,
-	 * never the authority for accepting append-only sync state.
-	 */
-	#computeDigest(messages: readonly unknown[]): MessageDigest {
-		return this.#computeDigestRange(messages, 0, messages.length);
+	#hashMessage(message: unknown): number | bigint {
+		return hashSource(JSON.stringify(message) ?? "null");
+	}
+
+	#hashRange(messages: readonly unknown[], start: number, end: number): (number | bigint)[] {
+		const out: (number | bigint)[] = [];
+		for (let i = start; i < end; i++) out.push(this.#hashMessage(messages[i]));
+		return out;
+	}
+
+	/** True when the first `count` messages of `a` and `b` are content-equal by per-message hash. */
+	#rangeHashesEqual(a: readonly unknown[], b: readonly unknown[], count: number): boolean {
+		for (let i = 0; i < count; i++) {
+			if (this.#hashMessage(a[i]) !== this.#hashMessage(b[i])) return false;
+		}
+		return true;
 	}
 
-	#computeDigestRange(messages: readonly unknown[], start: number, end: number): MessageDigest {
-		let source = "[";
-		for (let i = start; i < end; i++) {
-			if (i > start) source += ",";
-			source += JSON.stringify(messages[i]) ?? "null";
+	/** True when any of the first `count` already-synced messages changed content (in-place rewrite). */
+	#prefixChanged(messages: readonly unknown[], count: number): boolean {
+		if (count > this.#syncedHashes.length) return false;
+		for (let i = 0; i < count; i++) {
+			if (this.#hashMessage(messages[i]) !== this.#syncedHashes[i]) return true;
 		}
-		source += "]";
-		return { hash: hashSource(source), source };
+		return false;
+	}
+
+	/** F9: reset the seeded log to a new provider-visible baseline (seeded compaction/rebase). */
+	#rebaseToBaseline(messages: readonly unknown[]): void {
+		this.log.clear();
+		this.log.extend([...messages]);
+		this.#lastSyncCount = messages.length;
+		this.#seededPrefixCount = 0;
+		this.#syncedHashes = this.#hashRange(messages, 0, messages.length);
 	}
 }
 
@@ -350,15 +373,6 @@ export class AppendOnlyContextManager {
 // Snapshot helpers
 // ---------------------------------------------------------------------------
 
-type MessageDigest = {
-	hash: number | bigint;
-	source: string;
-};
-
-function emptyMessageDigest(): MessageDigest {
-	return { hash: hashSource("[]"), source: "[]" };
-}
-
 function hashSource(source: string): number | bigint {
 	return typeof Bun !== "undefined" ? Bun.hash(source) : hashString32(source);
 }

package/src/compaction/branch-summarization.ts

@@ -5,7 +5,7 @@
  * a summary of the branch being left so context isn't lost.
  */
 
-import type { Model } from "@gajae-code/ai";
+import type { Model, ProviderSessionState } from "@gajae-code/ai";
 import { prompt } from "@gajae-code/utils";
 import { type AgentTelemetry, instrumentedCompleteSimple } from "../telemetry";
 import type { AgentMessage } from "../types";
@@ -86,6 +86,15 @@ export interface GenerateBranchSummaryOptions {
 	 * wrapped in an OTEL chat span tagged with `pi.gen_ai.oneshot.kind = "branch_summary"`.
 	 */
 	telemetry?: AgentTelemetry;
+	/**
+	 * Provider session affinity id forwarded to the branch summary LLM call so it
+	 * reuses the live turn's provider/WebSocket session.
+	 */
+	sessionId?: string;
+	/** Shared provider state map so the branch summary call reuses session-scoped transport/session caches. */
+	providerSessionState?: Map<string, ProviderSessionState>;
+	/** Hint that websocket transport should be preferred when supported by the provider implementation. */
+	preferWebsockets?: boolean;
 }
 
 // ============================================================================
@@ -274,7 +283,17 @@ export async function generateBranchSummary(
 	entries: SessionEntry[],
 	options: GenerateBranchSummaryOptions,
 ): Promise<BranchSummaryResult> {
-	const { model, apiKey, signal, customInstructions, reserveTokens = 16384, metadata } = options;
+	const {
+		model,
+		apiKey,
+		signal,
+		customInstructions,
+		reserveTokens = 16384,
+		metadata,
+		sessionId,
+		providerSessionState,
+		preferWebsockets,
+	} = options;
 
 	// Token budget = context window minus reserved space for prompt + response
 	const contextWindow = model.contextWindow || 128000;
@@ -307,7 +326,7 @@ export async function generateBranchSummary(
 	const response = await instrumentedCompleteSimple(
 		model,
 		{ systemPrompt: [SUMMARIZATION_SYSTEM_PROMPT], messages: summarizationMessages },
-		{ apiKey, signal, maxTokens: 2048, metadata },
+		{ apiKey, signal, maxTokens: 2048, metadata, sessionId, providerSessionState, preferWebsockets },
 		{ telemetry: options.telemetry, oneshotKind: "branch_summary" },
 	);
 

package/src/compaction/compaction.ts

@@ -12,6 +12,7 @@ import {
 	type Message,
 	type MessageAttribution,
 	type Model,
+	type ProviderSessionState,
 	type Usage,
 } from "@gajae-code/ai";
 import { isCompiledBinary, logger, prompt } from "@gajae-code/utils";
@@ -236,6 +237,56 @@ export function shouldCompact(
 	return contextTokens > thresholdTokens;
 }
 
+/** Reason a compaction was triggered. `token` is the normal user-configurable path; the rest are emergency floors. */
+export type CompactionTriggerReason = "token" | "heap" | "providerBytes" | "messageCount" | "imageBytes";
+
+/** A point-in-time resource sample. Supplied by an injectable sampler so tests never read real RSS. */
+export interface EmergencyCompactionSample {
+	/** Resident heap bytes (e.g. process.memoryUsage().heapUsed). */
+	heapUsedBytes: number;
+	/** Approximate serialized provider-context bytes. */
+	providerBytes: number;
+	/** Provider-visible message count. */
+	messageCount: number;
+	/** Approximate inline image bytes in the provider context. */
+	imageBytes: number;
+}
+
+export interface EmergencyCompactionLimits {
+	heapUsedBytes: number;
+	providerBytes: number;
+	messageCount: number;
+	imageBytes: number;
+}
+
+/**
+ * Non-disableable emergency floors. These sit well above normal usage and exist so a
+ * long session on weak hardware compacts before OOM even when token-based compaction is
+ * disabled or its threshold is set too high. They are NOT user-tunable down to zero.
+ */
+export const DEFAULT_EMERGENCY_COMPACTION_LIMITS: EmergencyCompactionLimits = {
+	heapUsedBytes: 1_536 * 1024 * 1024, // 1.5 GiB resident heap
+	providerBytes: 24 * 1024 * 1024, // 24 MiB serialized provider context
+	messageCount: 4000,
+	imageBytes: 64 * 1024 * 1024, // 64 MiB inline image bytes
+};
+
+/**
+ * Returns the first emergency limit exceeded (heap > providerBytes > imageBytes > messageCount),
+ * or null when none is. Pure and sampler-injected; the caller routes the result through the
+ * normal pair-safe `compact()` cut logic so a tool_use/tool_result pair is never split.
+ */
+export function emergencyCompactionReason(
+	sample: EmergencyCompactionSample,
+	limits: EmergencyCompactionLimits = DEFAULT_EMERGENCY_COMPACTION_LIMITS,
+): CompactionTriggerReason | null {
+	if (sample.heapUsedBytes > limits.heapUsedBytes) return "heap";
+	if (sample.providerBytes > limits.providerBytes) return "providerBytes";
+	if (sample.imageBytes > limits.imageBytes) return "imageBytes";
+	if (sample.messageCount > limits.messageCount) return "messageCount";
+	return null;
+}
+
 export function resolveThresholdTokens(
 	contextWindow: number,
 	settings: CompactionSettings,
@@ -301,7 +352,18 @@ function nativeTokenizerEntrypoint(): string {
 	return isCompiledBinary() ? COMPILED_NATIVE_TOKENIZER_ENTRYPOINT : SOURCE_NATIVE_TOKENIZER_ENTRYPOINT;
 }
 
+/** Max total fragment chars sent to the synchronous native tokenizer (F22). */
+const MAX_NATIVE_TOKENIZE_CHARS = 2 * 1024 * 1024;
+
 function nativeCountTokens(fragments: string[]): number {
+	let totalChars = 0;
+	for (const fragment of fragments) totalChars += fragment.length;
+	if (totalChars > MAX_NATIVE_TOKENIZE_CHARS) {
+		// F22: skip the synchronous native BPE tokenizer (materializes a ~39MB table and is
+		// O(text)) on pathologically large inputs; the cheap chars/token heuristic is more
+		// than accurate enough for size/budget decisions and never blocks the event loop.
+		return estimateTextTokensHeuristic(fragments);
+	}
 	if (!cachedNativeCountTokens) {
 		const natives = requireFromCompaction(nativeTokenizerEntrypoint()) as NativeTokenizerModule;
 		cachedNativeCountTokens = natives.countTokens;
@@ -674,6 +736,16 @@ export interface SummaryOptions {
 	 */
 	telemetry?: AgentTelemetry;
 	authCredentialType?: "api_key" | "oauth";
+	/**
+	 * Provider session affinity id forwarded to the maintenance LLM call so it
+	 * reuses the live turn's provider/WebSocket session (matches the
+	 * `providerSessionId ?? sessionId` the agent loop sends for normal turns).
+	 */
+	sessionId?: string;
+	/** Shared provider state map so maintenance calls reuse session-scoped transport/session caches. */
+	providerSessionState?: Map<string, ProviderSessionState>;
+	/** Hint that websocket transport should be preferred when supported by the provider implementation. */
+	preferWebsockets?: boolean;
 }
 
 export async function generateSummary(
@@ -740,6 +812,9 @@ export async function generateSummary(
 			reasoning: Effort.High,
 			initiatorOverride: options?.initiatorOverride,
 			metadata: options?.metadata,
+			sessionId: options?.sessionId,
+			providerSessionState: options?.providerSessionState,
+			preferWebsockets: options?.preferWebsockets,
 		},
 		{ telemetry: options?.telemetry, oneshotKind: "compaction_summary" },
 	);
@@ -775,6 +850,15 @@ export interface HandoffOptions {
 	 */
 	telemetry?: AgentTelemetry;
 	authCredentialType?: "api_key" | "oauth";
+	/**
+	 * Provider session affinity id forwarded to the handoff LLM call so it
+	 * reuses the live turn's provider/WebSocket session.
+	 */
+	sessionId?: string;
+	/** Shared provider state map so the handoff call reuses session-scoped transport/session caches. */
+	providerSessionState?: Map<string, ProviderSessionState>;
+	/** Hint that websocket transport should be preferred when supported by the provider implementation. */
+	preferWebsockets?: boolean;
 }
 
 export function renderHandoffPrompt(customInstructions?: string): string {
@@ -816,6 +900,9 @@ export async function generateHandoff(
 			toolChoice: "none",
 			initiatorOverride: options.initiatorOverride,
 			metadata: options.metadata,
+			sessionId: options.sessionId,
+			providerSessionState: options.providerSessionState,
+			preferWebsockets: options.preferWebsockets,
 		},
 		{ telemetry: options.telemetry, oneshotKind: "handoff" },
 	);
@@ -875,6 +962,9 @@ async function generateShortSummary(
 			reasoning: Effort.High,
 			initiatorOverride: options?.initiatorOverride,
 			metadata: options?.metadata,
+			sessionId: options?.sessionId,
+			providerSessionState: options?.providerSessionState,
+			preferWebsockets: options?.preferWebsockets,
 		},
 		{ telemetry: options?.telemetry, oneshotKind: "compaction_short_summary" },
 	);
@@ -1059,6 +1149,9 @@ export async function compact(
 		metadata: options?.metadata,
 		convertToLlm: options?.convertToLlm,
 		telemetry: options?.telemetry,
+		sessionId: options?.sessionId,
+		providerSessionState: options?.providerSessionState,
+		preferWebsockets: options?.preferWebsockets,
 	};
 
 	let preserveData = withOpenAiRemoteCompactionPreserveData(previousPreserveData, undefined);
@@ -1098,9 +1191,22 @@ export async function compact(
 	// Generate summaries (can be parallel if both needed) and merge into one
 	let summary: string;
 
+	// A single active Codex WebSocket session cannot service two concurrent
+	// requests ("websocket request already in progress"). When the maintenance
+	// calls use the Codex Responses provider, share one provider session, and
+	// websocket transport is not explicitly disabled, run the split-turn history
+	// and turn-prefix summaries sequentially. This covers websocket activation
+	// from config/env/model defaults too: the provider can select websockets even
+	// when `preferWebsockets` is undefined, while non-Codex providers keep the
+	// previous parallel behavior.
+	const summariesMayShareWebSocketSession = Boolean(
+		model.api === "openai-codex-responses" &&
+			summaryOptions.providerSessionState &&
+			summaryOptions.preferWebsockets !== false,
+	);
+
 	if (isSplitTurn && turnPrefixMessages.length > 0) {
-		// Generate both summaries in parallel
-		const [historyResult, turnPrefixResult] = await Promise.all([
+		const runHistorySummary = () =>
 			messagesToSummarize.length > 0
 				? generateSummary(
 						messagesToSummarize,
@@ -1112,9 +1218,19 @@ export async function compact(
 						previousSummary,
 						summaryOptions,
 					)
-				: Promise.resolve("No prior history."),
-			generateTurnPrefixSummary(turnPrefixMessages, model, settings.reserveTokens, apiKey, signal, summaryOptions),
-		]);
+				: Promise.resolve("No prior history.");
+		const runTurnPrefixSummary = () =>
+			generateTurnPrefixSummary(turnPrefixMessages, model, settings.reserveTokens, apiKey, signal, summaryOptions);
+
+		let historyResult: string;
+		let turnPrefixResult: string;
+		if (summariesMayShareWebSocketSession) {
+			// Sequential: avoids concurrent requests on the same provider session.
+			historyResult = await runHistorySummary();
+			turnPrefixResult = await runTurnPrefixSummary();
+		} else {
+			[historyResult, turnPrefixResult] = await Promise.all([runHistorySummary(), runTurnPrefixSummary()]);
+		}
 		// Merge into single summary
 		summary = `${historyResult}\n\n---\n\n**Turn Context (split turn):**\n\n${turnPrefixResult}`;
 	} else if (messagesToSummarize.length > 0) {
@@ -1150,6 +1266,9 @@ export async function compact(
 			initiatorOverride: summaryOptions.initiatorOverride,
 			metadata: summaryOptions.metadata,
 			telemetry: summaryOptions.telemetry,
+			sessionId: summaryOptions.sessionId,
+			providerSessionState: summaryOptions.providerSessionState,
+			preferWebsockets: summaryOptions.preferWebsockets,
 		},
 	);
 
@@ -1205,6 +1324,9 @@ async function generateTurnPrefixSummary(
 			reasoning: Effort.High,
 			initiatorOverride: options?.initiatorOverride,
 			metadata: options?.metadata,
+			sessionId: options?.sessionId,
+			providerSessionState: options?.providerSessionState,
+			preferWebsockets: options?.preferWebsockets,
 		},
 		{ telemetry: options?.telemetry, oneshotKind: "compaction_turn_prefix" },
 	);