@gajae-code/agent-core 0.5.3 → 0.5.4

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [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

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";
@@ -182,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 {
@@ -199,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.3",
+	"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.3",
-		"@gajae-code/natives": "0.5.3",
-		"@gajae-code/utils": "0.5.3",
+		"@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

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";
@@ -735,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(
@@ -801,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" },
 	);
@@ -836,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 {
@@ -877,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" },
 	);
@@ -936,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" },
 	);
@@ -1120,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);
@@ -1159,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,
@@ -1173,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) {
@@ -1211,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,
 		},
 	);
 
@@ -1266,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" },
 	);