@gajae-code/agent-core 0.16.3 → 0.16.4

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.16.4] - 2026-09-05
+
+- Provider calls now carry the agent-owned opaque provider conversation identity separately from generic session/cache affinity, including compaction, handoff, turn-prefix summary, and branch-summary maintenance calls. This lets provider-specific conversation headers remain stable without treating prompt-derived gateway cache keys as conversation authority (#5295).
+
+- Failed cooperative context maintenance now terminalizes the active run with its concrete maintenance error instead of advertising a continuation over unchanged context. Only committed prune, compaction, or promotion outcomes remain resumable.
+
 ## [0.16.3] - 2026-09-04
 
 ## [0.16.2] - 2026-09-04

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

@@ -62,6 +62,8 @@ export interface GenerateBranchSummaryOptions {
      * reuses the live turn's provider/WebSocket session.
      */
     sessionId?: string;
+    /** Opaque provider conversation identity; never derived from branch-summary content. */
+    providerSessionId?: 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. */

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

@@ -209,6 +209,8 @@ export interface SummaryOptions {
      * `providerSessionId ?? sessionId` the agent loop sends for normal turns).
      */
     sessionId?: string;
+    /** Opaque provider conversation identity; never derived from compaction content. */
+    providerSessionId?: 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. */
@@ -262,6 +264,8 @@ export interface HandoffOptions {
      * reuses the live turn's provider/WebSocket session.
      */
     sessionId?: string;
+    /** Opaque provider conversation identity; never derived from handoff content. */
+    providerSessionId?: 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. */

package/dist/types/types.d.ts

@@ -195,14 +195,16 @@ export type ManagedAttemptOutcomeHandler = (outcome: ManagedAttemptOutcome) => M
  * Outcome of a cooperative mid-run context-maintenance checkpoint (see
  * {@link AgentLoopConfig.maintainContext}). Any value other than "not-needed"
  * means the checkpoint mutated (or attempted to mutate) durable context, so the
- * loop ends the current run without the lossy `agent_end` finalization and the
- * maintenance owner resumes the run on the rewritten context.
+ * loop ends the current run without lossy finalization. Committed maintenance
+ * resumes on rewritten context; failed or aborted maintenance terminalizes.
  */
 export type MidRunMaintenanceOutcome = "not-needed" | "pruned" | "compacted" | "promoted" | "failed" | "aborted";
 export interface ContextMaintenanceResult {
     outcome: MidRunMaintenanceOutcome;
     releaseCurrentContext?: boolean;
+    errorMessage?: string;
 }
+export declare function isContinuingMidRunMaintenanceOutcome(outcome: unknown): boolean;
 /**
  * Configuration for the agent loop.
  */
@@ -407,9 +409,9 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * non-optional loop signal, and `awaitEventDrain(invocationSignal)` waits for
      * prior event consumer bodies with loop and invocation cancellation composed.
      * Any outcome other than "not-needed" ends the current run with
-     * `agent_end.stopReason === "maintenance"` (NOT the lossy pause / completed
-     * finalization); the callback's continuation owner resumes the run on the
-     * rewritten context.
+     * `agent_end.stopReason === "maintenance"`. Successful maintenance resumes
+     * on rewritten context; `failed` and `aborted` are terminal and never resend
+     * the unchanged context.
      */
     maintainContext?: (context: AgentContext, lifecycle: {
         signal: AbortSignal;

package/package.json

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

package/src/agent-loop.ts

@@ -89,6 +89,7 @@ import {
 	type AgentTool,
 	type AgentToolContext,
 	type AgentToolResult,
+	isContinuingMidRunMaintenanceOutcome,
 	type ManagedAttemptOutcome,
 	type StandaloneRunOwnership,
 	type StreamFn,
@@ -1260,13 +1261,12 @@ function publishAgentEnd(
 	event: Extract<AgentEvent, { type: "agent_end" }>,
 	scope?: AttemptScope,
 ): void {
-	// Aborted maintenance yields no continuation, so it is terminal for standalone
-	// ownership and resource sealing. The event itself keeps its `maintenance`
-	// stopReason so AgentSession can still report the aborted maintenance
-	// settlement to its consumers.
+	// Only maintenance that committed a context mutation can continue. Failed and
+	// aborted maintenance are terminal so the unchanged context is never resent.
 	const publishedEvent = scope ? { ...event, scope } : event;
 	const maintenanceContinues =
-		publishedEvent.stopReason === "maintenance" && publishedEvent.maintenanceOutcome !== "aborted";
+		publishedEvent.stopReason === "maintenance" &&
+		isContinuingMidRunMaintenanceOutcome(publishedEvent.maintenanceOutcome);
 	stream.push(publishedEvent);
 	const standalone = config.standaloneRunOwnership
 		? standaloneOwnershipStates.get(config.standaloneRunOwnership)
@@ -3739,6 +3739,16 @@ async function runLoopBody(
 				}
 
 				if (outcome !== "not-needed") {
+					if (outcome === "failed") {
+						const errorMessage =
+							maintenance.errorMessage ??
+							"Context maintenance failed before the next model request; the unchanged context was not resubmitted.";
+						const message = managedFailureMessage(new Error(errorMessage), config);
+						stream.push({ type: "message_start", message, scope: attemptScope });
+						stream.push({ type: "message_end", message, scope: attemptScope });
+						currentContext.messages.push(message);
+						newMessages.push(message);
+					}
 					publishAgentEnd(
 						stream,
 						config,
@@ -4639,6 +4649,7 @@ async function streamAssistantResponse(
 						authCredentialType,
 						metadata: resolvedMetadata,
 						sessionId: config.providerSessionId ?? config.sessionId,
+						providerSessionId: config.providerSessionId,
 						toolChoice: effectiveToolChoice,
 						reasoning: effectiveReasoning,
 						temperature: effectiveTemperature,

package/src/agent.ts

@@ -54,7 +54,7 @@ import type {
 	StreamFn,
 	ToolCallContext,
 } from "./types";
-import { setAgentTerminalOwnerContext } from "./types";
+import { isContinuingMidRunMaintenanceOutcome, setAgentTerminalOwnerContext } from "./types";
 
 /**
  * Closed runtime allowlist of failure-classifier codes. The public diagnostic
@@ -118,7 +118,7 @@ function sanitizeAgentFailure(error: unknown, runtimeClassifiedCode?: string): {
 }
 
 /** Only runtime-authenticated built-in constructors may contribute a name. */
-const TRUSTED_ERROR_CONSTRUCTORS = new Map<Function, string>([
+const TRUSTED_ERROR_CONSTRUCTORS = new Map<object, string>([
 	[Error, "Error"],
 	[TypeError, "TypeError"],
 	[RangeError, "RangeError"],
@@ -2147,12 +2147,15 @@ export class Agent {
 						}
 						this.#state.isStreaming = false;
 						this.#state.streamMessage = null;
-						// A maintenance checkpoint is only non-terminal while a continuation will
-						// follow. An aborted maintenance yields none, and because the loop runs with
+						// A maintenance checkpoint is only non-terminal while a committed rewrite
+						// will continue. Failed or aborted maintenance yields none. Because the loop runs with
 						// `resourceSealOwner: "caller"` it deliberately leaves sealing to us, so
 						// treating it as a checkpoint here would leave the run open forever and make
 						// every cancel report `run_not_sealed`.
-						if (event.stopReason === "maintenance" && event.maintenanceOutcome !== "aborted") {
+						if (
+							event.stopReason === "maintenance" &&
+							isContinuingMidRunMaintenanceOutcome(event.maintenanceOutcome)
+						) {
 							this.#managedLogicalRunOwner ??= managedLogicalRunOwner ?? runId;
 							maintenanceInterrupted = true;
 							this.#emit(event);

package/src/compaction/branch-summarization.ts

@@ -91,6 +91,8 @@ export interface GenerateBranchSummaryOptions {
 	 * reuses the live turn's provider/WebSocket session.
 	 */
 	sessionId?: string;
+	/** Opaque provider conversation identity; never derived from branch-summary content. */
+	providerSessionId?: 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. */
@@ -291,6 +293,7 @@ export async function generateBranchSummary(
 		reserveTokens = 16384,
 		metadata,
 		sessionId,
+		providerSessionId,
 		providerSessionState,
 		preferWebsockets,
 	} = options;
@@ -326,7 +329,16 @@ export async function generateBranchSummary(
 	const response = await instrumentedCompleteSimple(
 		model,
 		{ systemPrompt: [SUMMARIZATION_SYSTEM_PROMPT], messages: summarizationMessages },
-		{ apiKey, signal, maxTokens: 2048, metadata, sessionId, providerSessionState, preferWebsockets },
+		{
+			apiKey,
+			signal,
+			maxTokens: 2048,
+			metadata,
+			sessionId,
+			providerSessionId,
+			providerSessionState,
+			preferWebsockets,
+		},
 		{ telemetry: options.telemetry, oneshotKind: "branch_summary" },
 	);
 

package/src/compaction/compaction.ts

@@ -882,6 +882,8 @@ export interface SummaryOptions {
 	 * `providerSessionId ?? sessionId` the agent loop sends for normal turns).
 	 */
 	sessionId?: string;
+	/** Opaque provider conversation identity; never derived from compaction content. */
+	providerSessionId?: 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. */
@@ -1025,6 +1027,7 @@ export async function generateSummary(
 			initiatorOverride: options?.initiatorOverride,
 			metadata: options?.metadata,
 			sessionId: options?.sessionId,
+			providerSessionId: options?.providerSessionId,
 			providerSessionState: options?.providerSessionState,
 			preferWebsockets: options?.preferWebsockets,
 		},
@@ -1073,6 +1076,8 @@ export interface HandoffOptions {
 	 * reuses the live turn's provider/WebSocket session.
 	 */
 	sessionId?: string;
+	/** Opaque provider conversation identity; never derived from handoff content. */
+	providerSessionId?: 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. */
@@ -1120,6 +1125,7 @@ export async function generateHandoff(
 			initiatorOverride: options.initiatorOverride,
 			metadata: options.metadata,
 			sessionId: options.sessionId,
+			providerSessionId: options.providerSessionId,
 			providerSessionState: options.providerSessionState,
 			preferWebsockets: options.preferWebsockets,
 		},
@@ -1378,6 +1384,7 @@ export async function compact(
 		convertToLlm: options?.convertToLlm,
 		telemetry: options?.telemetry,
 		sessionId: options?.sessionId,
+		providerSessionId: options?.providerSessionId,
 		providerSessionState: options?.providerSessionState,
 		preferWebsockets: options?.preferWebsockets,
 		remoteCompactionFallbackHealth: options?.remoteCompactionFallbackHealth,
@@ -1552,6 +1559,7 @@ async function generateTurnPrefixSummary(
 			initiatorOverride: options?.initiatorOverride,
 			metadata: options?.metadata,
 			sessionId: options?.sessionId,
+			providerSessionId: options?.providerSessionId,
 			providerSessionState: options?.providerSessionState,
 			preferWebsockets: options?.preferWebsockets,
 		},

package/src/types.ts

@@ -214,14 +214,19 @@ export type ManagedAttemptOutcomeHandler = (
  * Outcome of a cooperative mid-run context-maintenance checkpoint (see
  * {@link AgentLoopConfig.maintainContext}). Any value other than "not-needed"
  * means the checkpoint mutated (or attempted to mutate) durable context, so the
- * loop ends the current run without the lossy `agent_end` finalization and the
- * maintenance owner resumes the run on the rewritten context.
+ * loop ends the current run without lossy finalization. Committed maintenance
+ * resumes on rewritten context; failed or aborted maintenance terminalizes.
  */
 export type MidRunMaintenanceOutcome = "not-needed" | "pruned" | "compacted" | "promoted" | "failed" | "aborted";
 
 export interface ContextMaintenanceResult {
 	outcome: MidRunMaintenanceOutcome;
 	releaseCurrentContext?: boolean;
+	errorMessage?: string;
+}
+
+export function isContinuingMidRunMaintenanceOutcome(outcome: unknown): boolean {
+	return outcome === "pruned" || outcome === "compacted" || outcome === "promoted";
 }
 
 /**
@@ -438,9 +443,9 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 * non-optional loop signal, and `awaitEventDrain(invocationSignal)` waits for
 	 * prior event consumer bodies with loop and invocation cancellation composed.
 	 * Any outcome other than "not-needed" ends the current run with
-	 * `agent_end.stopReason === "maintenance"` (NOT the lossy pause / completed
-	 * finalization); the callback's continuation owner resumes the run on the
-	 * rewritten context.
+	 * `agent_end.stopReason === "maintenance"`. Successful maintenance resumes
+	 * on rewritten context; `failed` and `aborted` are terminal and never resend
+	 * the unchanged context.
 	 */
 	maintainContext?: (
 		context: AgentContext,