@gajae-code/agent-core 0.11.1 → 0.11.2

package/src/agent.ts

@@ -308,6 +308,11 @@ interface CursorToolResultEntry {
 	textLengthAtCall: number;
 }
 
+export type AgentQueueSnapshot = {
+	steering: AgentMessage[];
+	followUp: AgentMessage[];
+};
+
 export class Agent {
 	#state: AgentState = {
 		systemPrompt: [],
@@ -1009,6 +1014,20 @@ export class Agent {
 		this.#followUpQueue = [...messages, ...this.#followUpQueue];
 	}
 
+	/** Snapshot both executable queues as one atomic session-level view. */
+	snapshotQueues(): AgentQueueSnapshot {
+		return {
+			steering: this.#steeringQueue.slice(),
+			followUp: this.#followUpQueue.slice(),
+		};
+	}
+
+	/** Replace both executable queues with a prior snapshot. */
+	restoreQueues(snapshot: AgentQueueSnapshot): void {
+		this.#steeringQueue = snapshot.steering.slice();
+		this.#followUpQueue = snapshot.followUp.slice();
+	}
+
 	#dequeueSteeringMessages(): AgentMessage[] {
 		if (this.#steeringMode === "one-at-a-time") {
 			if (this.#steeringQueue.length > 0) {
@@ -1607,7 +1626,7 @@ export class Agent {
 					this.requestRunTerminal(managedLogicalRunOwner ?? runId, managedDecision.terminal);
 				} else if (managedOutcome.type === "run_terminal") {
 					this.requestRunTerminal(managedLogicalRunOwner ?? runId, { stopReason: managedOutcome.reason });
-				} else if (managedDecision?.type !== "retry") {
+				} else if (managedDecision?.type !== "retry" && managedDecision?.type !== "maintenance") {
 					this.#finalizeRun(managedLogicalRunOwner ?? runId);
 				}
 			}
@@ -1660,7 +1679,10 @@ export class Agent {
 			});
 		} finally {
 			let continuation: ManagedAttemptContinuation | undefined;
-			if (managedOutcome?.type === "retryable_discarded" && managedDecision?.type === "retry") {
+			if (
+				managedOutcome?.type !== "run_terminal" &&
+				(managedDecision?.type === "retry" || managedDecision?.type === "maintenance")
+			) {
 				continuation = managedDecision.continuation;
 			}
 			const ownership: ManagedAttemptContinuationOwnership = {
@@ -1691,7 +1713,18 @@ export class Agent {
 			if (continuation && ownership.isCurrent()) {
 				try {
 					await continuation(ownership);
-					if (this.#activeRunId === undefined && this.#managedLogicalRunOwner === managedLogicalRunOwner) {
+					if (
+						managedDecision?.type === "maintenance" &&
+						this.#terminalizedLogicalRunIds.has(managedLogicalRunOwner ?? runId) &&
+						this.#managedLogicalRunOwner === managedLogicalRunOwner
+					) {
+						this.#managedLogicalRunOwner = undefined;
+					}
+					if (
+						managedDecision?.type !== "maintenance" &&
+						this.#activeRunId === undefined &&
+						this.#managedLogicalRunOwner === managedLogicalRunOwner
+					) {
 						this.#managedLogicalRunOwner = undefined;
 					}
 				} catch (err) {

package/src/compaction/compaction.ts

@@ -29,7 +29,6 @@ import {
 	withOpenAiRemoteCompactionPreserveData,
 } from "./openai";
 import autoHandoffThresholdFocusPrompt from "./prompts/auto-handoff-threshold-focus.md" with { type: "text" };
-import compactionShortSummaryPrompt from "./prompts/compaction-short-summary.md" with { type: "text" };
 import compactionSummaryPrompt from "./prompts/compaction-summary.md" with { type: "text" };
 import compactionTurnPrefixPrompt from "./prompts/compaction-turn-prefix.md" with { type: "text" };
 import compactionUpdateSummaryPrompt from "./prompts/compaction-update-summary.md" with { type: "text" };
@@ -510,7 +509,8 @@ function collectMessageFragments(message: AgentMessage): { fragments: string[];
 	}
 
 	switch (message.role) {
-		case "user": {
+		case "user":
+		case "custom": {
 			const content = (message as { content: string | Array<{ type: string; text?: string }> }).content;
 			if (typeof content === "string") {
 				fragments.push(content);
@@ -710,8 +710,6 @@ export function findCutPoint(
 
 	for (let i = endIndex - 1; i >= startIndex; i--) {
 		const entry = entries[i];
-		if (entry.type !== "message") continue;
-
 		// Estimate this message's size
 		const messageTokens = estimateEntryTokens(entry);
 		accumulatedTokens += messageTokens;
@@ -769,8 +767,6 @@ const SUMMARIZATION_PROMPT = prompt.render(compactionSummaryPrompt);
 
 const UPDATE_SUMMARIZATION_PROMPT = prompt.render(compactionUpdateSummaryPrompt);
 
-const SHORT_SUMMARY_PROMPT = prompt.render(compactionShortSummaryPrompt);
-
 const HANDOFF_DOCUMENT_PROMPT = prompt.render(handoffDocumentPrompt);
 
 export const AUTO_HANDOFF_THRESHOLD_FOCUS = prompt.render(autoHandoffThresholdFocusPrompt);
@@ -796,8 +792,7 @@ export interface SummaryOptions {
 	/**
 	 * Optional telemetry handle. When provided, every LLM call emitted during
 	 * compaction is wrapped in an OTEL chat span tagged with
-	 * `pi.gen_ai.oneshot.kind` (`compaction_summary`, `compaction_short_summary`,
-	 * or `compaction_turn_prefix`). `undefined` keeps the call paths zero-cost.
+	 * `pi.gen_ai.oneshot.kind` (`compaction_summary` or `compaction_turn_prefix`).
 	 */
 	telemetry?: AgentTelemetry;
 	authCredentialType?: "api_key" | "oauth";
@@ -1054,66 +1049,11 @@ export async function generateHandoff(
 		.join("\n");
 }
 
-async function generateShortSummary(
-	recentMessages: AgentMessage[],
-	historySummary: string | undefined,
-	model: Model,
-	reserveTokens: number,
-	apiKey: string,
-	signal?: AbortSignal,
-	options?: SummaryOptions,
-): Promise<string> {
-	const maxTokens = Math.min(512, Math.floor(0.2 * reserveTokens));
-	const llmMessages = (options?.convertToLlm ?? convertToLlm)(recentMessages);
-	const conversationText = boundConversationTextForSummary(serializeConversation(llmMessages), model, maxTokens);
-
-	let promptText = `<conversation>\n${conversationText}\n</conversation>\n\n`;
-	if (historySummary) {
-		promptText += `<previous-summary>\n${historySummary}\n</previous-summary>\n\n`;
-	}
-	promptText += formatAdditionalContext(options?.extraContext);
-	promptText += SHORT_SUMMARY_PROMPT;
-
-	if (options?.remoteEndpoint) {
-		const remote = await requestRemoteCompaction(
-			options.remoteEndpoint,
-			{
-				systemPrompt: SUMMARIZATION_SYSTEM_PROMPT,
-				prompt: promptText,
-			},
-			signal,
-		);
-		return remote.summary;
-	}
-
-	const response = await instrumentedCompleteSimple(
-		model,
-		{
-			systemPrompt: [SUMMARIZATION_SYSTEM_PROMPT],
-			messages: [{ role: "user", content: [{ type: "text", text: promptText }], timestamp: Date.now() }],
-		},
-		{
-			maxTokens,
-			signal,
-			apiKey,
-			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" },
-	);
-
-	if (response.stopReason === "error") {
-		throw new Error(`Short summary failed: ${response.errorMessage || "Unknown error"}`);
-	}
-
-	return response.content
-		.filter((c): c is { type: "text"; text: string } => c.type === "text")
-		.map(c => c.text)
-		.join("\n");
+/** Derive a display summary locally to avoid a second compaction LLM request. */
+function deriveShortSummary(summary: string): string {
+	const firstParagraph = summary.trim().split(/\n\s*\n/, 1)[0] ?? "";
+	const maxLength = 2_000;
+	return firstParagraph.length <= maxLength ? firstParagraph : `${firstParagraph.slice(0, maxLength - 1)}…`;
 }
 
 // ============================================================================
@@ -1163,6 +1103,11 @@ export interface PrepareCompactionOptions {
 	 * (the confounded raw promptTokens/estimatedTokens quotient is never used).
 	 */
 	tokenCorrectionRatio?: number;
+	/**
+	 * Model context-window size. Windows below 66k retain the legacy fixed
+	 * keepRecentTokens behavior; larger windows scale the keep window to 30%.
+	 */
+	contextWindow?: number;
 }
 
 export function prepareCompaction(
@@ -1193,13 +1138,42 @@ export function prepareCompaction(
 	// counts system+tools+full history while estimatedTokens counted only the
 	// post-boundary slice, so it was confounded and only ever shrank the window.
 	// Here the correction is bidirectional and clamped to [0.5, 2].
-	const keepRecentTokens = settings.keepRecentTokens;
+	const configuredKeepRecentTokens = settings.keepRecentTokens;
+	const contextWindow = options.contextWindow;
+	const thresholdSafeKeepRecentTokens =
+		contextWindow !== undefined && Number.isFinite(contextWindow) && contextWindow > 1
+			? Math.max(
+					1,
+					resolveThresholdTokens(contextWindow, settings) - effectiveReserveTokens(contextWindow, settings, 0),
+				)
+			: configuredKeepRecentTokens;
+	const keepRecentTokens = Math.min(configuredKeepRecentTokens, thresholdSafeKeepRecentTokens);
+	// Preserve the legacy fixed window for smaller models. At 66k and above,
+	// retain up to 30% of the model context, but never enough to leave the
+	// post-compaction prompt immediately above its configured threshold.
+	const scaledKeepRecentTokens =
+		contextWindow !== undefined && Number.isFinite(contextWindow) && contextWindow >= 66_000
+			? Math.min(thresholdSafeKeepRecentTokens, Math.max(keepRecentTokens, Math.floor(contextWindow * 0.3)))
+			: keepRecentTokens;
 	const rawRatio = options.tokenCorrectionRatio;
 	const appliedRatio =
 		rawRatio !== undefined && Number.isFinite(rawRatio) && rawRatio > 0
 			? Math.min(TOKEN_CORRECTION_MAX_RATIO, Math.max(TOKEN_CORRECTION_MIN_RATIO, rawRatio))
 			: 1;
-	const keepRecentTokensCorrected = Math.max(1, Math.round(keepRecentTokens / appliedRatio));
+	// Preserve an explicit keep floor that already covers the whole history: manual
+	// and emergency callers rely on prepareCompaction returning undefined rather
+	// than manufacturing a summary with no useful reduction. Otherwise, a scaled
+	// window that exceeds a short history falls back to the threshold-safe floor.
+	const historyTokens = pathEntries
+		.slice(boundaryStart, boundaryEnd)
+		.reduce((tokens, entry) => tokens + estimateEntryTokens(entry), 0);
+	const effectiveKeepRecentTokens =
+		configuredKeepRecentTokens > historyTokens
+			? configuredKeepRecentTokens
+			: scaledKeepRecentTokens > keepRecentTokens && scaledKeepRecentTokens > historyTokens
+				? keepRecentTokens
+				: scaledKeepRecentTokens;
+	const keepRecentTokensCorrected = Math.max(1, Math.round(effectiveKeepRecentTokens / appliedRatio));
 
 	const cutPoint = findCutPoint(pathEntries, boundaryStart, boundaryEnd, keepRecentTokensCorrected);
 
@@ -1437,28 +1411,10 @@ export async function compact(
 		summary = "No prior history.";
 	}
 
-	const shortSummary = await generateShortSummary(
-		recentMessages,
-		summary,
-		model,
-		settings.reserveTokens,
-		apiKey,
-		signal,
-		{
-			extraContext: options?.extraContext,
-			remoteEndpoint: summaryOptions.remoteEndpoint,
-			initiatorOverride: summaryOptions.initiatorOverride,
-			metadata: summaryOptions.metadata,
-			telemetry: summaryOptions.telemetry,
-			sessionId: summaryOptions.sessionId,
-			providerSessionState: summaryOptions.providerSessionState,
-			preferWebsockets: summaryOptions.preferWebsockets,
-		},
-	);
-
 	// Compute file lists and append to summary
 	const { readFiles, modifiedFiles } = computeFileLists(fileOps);
 	summary = upsertFileOperations(summary, readFiles, modifiedFiles);
+	const shortSummary = deriveShortSummary(summary);
 
 	if (!firstKeptEntryId) {
 		throw new Error("First kept entry has no ID - session may need migration");

package/src/compaction/pruning.ts

@@ -267,6 +267,56 @@ function readBasePath(path: string): string {
 	return base;
 }
 
+type ReadLineRange = { start: number; end: number };
+
+const DEFAULT_READ_LINE_LIMIT = 500;
+
+/** Parse trailing read selectors using the read tool's actual bounded default. */
+function readLineRanges(path: string): ReadLineRange[] {
+	let target = path;
+	let raw = false;
+	while (/:(?:raw|conflicts)$/.test(target)) {
+		raw ||= target.endsWith(":raw");
+		target = target.replace(/:(?:raw|conflicts)$/, "");
+	}
+	const match = target.match(/:(\d+(?:[-+]\d+)?(?:,\d+(?:[-+]\d+)?)*)$/);
+	if (!match) return raw ? [{ start: 1, end: Number.POSITIVE_INFINITY }] : [];
+	return match[1].split(",").flatMap(part => {
+		const range = part.match(/^(\d+)(?:([-+])(\d+))?$/);
+		if (!range) return [];
+		const start = Number(range[1]);
+		const end =
+			range[2] === "+"
+				? start + Number(range[3]) - 1
+				: range[2] === "-"
+					? Number(range[3])
+					: start + DEFAULT_READ_LINE_LIMIT - 1;
+		return start > 0 && end >= start ? [{ start, end }] : [];
+	});
+}
+
+function strictlyContainsReadRange(container: ReadLineRange, contained: ReadLineRange): boolean {
+	return (
+		container.start <= contained.start &&
+		container.end >= contained.end &&
+		(container.start < contained.start || container.end > contained.end)
+	);
+}
+
+function readSupersedesRead(
+	later: ToolCall,
+	earlier: ToolCall,
+	lineRangesByCall: ReadonlyMap<ToolCall, ReadLineRange[]>,
+): boolean {
+	const laterRanges = lineRangesByCall.get(later);
+	const earlierRanges = lineRangesByCall.get(earlier);
+	return (
+		laterRanges?.length === 1 &&
+		earlierRanges?.length === 1 &&
+		strictlyContainsReadRange(laterRanges[0], earlierRanges[0])
+	);
+}
+
 /**
  * Stable identity for "the same logical lookup": same tool re-targeting the
  * same subject. A later result with the same key supersedes earlier ones.
@@ -275,9 +325,23 @@ function readBasePath(path: string): string {
  * (`skip`) and result-shaping flags (`i`, `gitignore`): a later page or a
  * differently-shaped search complements earlier output, it does not replace it.
  */
+const IDEMPOTENT_BASH_COMMAND =
+	/^(?:(?:bun|npm|pnpm|yarn)\s+(?:run\s+)?(?:test|build)\b|git\s+status\b|cargo\s+build\b|(?:make|just)\s+build\b)/;
+
+function normalizedIdempotentBashCommand(call: ToolCall): string | undefined {
+	if (call.name !== "bash") return undefined;
+	const command = call.arguments.command;
+	if (typeof command !== "string") return undefined;
+	const normalized = command.trim().replace(/\s+/g, " ");
+	if (/[;&|]/.test(normalized) || !IDEMPOTENT_BASH_COMMAND.test(normalized)) return undefined;
+	return JSON.stringify([normalized, typeof call.arguments.cwd === "string" ? call.arguments.cwd : undefined]);
+}
+
 function toolTargetKey(call: ToolCall): string | undefined {
 	const path = toolCallPath(call);
 	if (path !== undefined) return JSON.stringify([call.name, "path", path]);
+	const command = normalizedIdempotentBashCommand(call);
+	if (command !== undefined) return JSON.stringify([call.name, "command", command]);
 	const pattern = call.arguments.pattern;
 	if (typeof pattern === "string" && pattern.length > 0) {
 		const paths = call.arguments.paths;
@@ -372,8 +436,9 @@ function buildStalenessIndex(entries: SessionEntry[]): StalenessIndex {
 		}
 	}
 
+	type ResultMeta = { key?: string; call: ToolCall; message: ToolResultMessage };
 	const lastResultIndexByKey = new Map<string, number>();
-	const resultMeta = new Map<number, { key?: string; call: ToolCall; message: ToolResultMessage }>();
+	const resultMeta = new Map<number, ResultMeta>();
 	const lastEditIndexByPath = new Map<string, number>();
 
 	for (let i = 0; i < entries.length; i++) {
@@ -439,6 +504,31 @@ function buildStalenessIndex(entries: SessionEntry[]): StalenessIndex {
 		}
 	}
 
+	const readsByBasePath = new Map<string, Array<[number, ResultMeta]>>();
+	const lineRangesByCall = new Map<ToolCall, ReadLineRange[]>();
+	for (const [index, meta] of resultMeta) {
+		if (meta.call.name !== "read") continue;
+		const path = toolCallPath(meta.call);
+		if (!path) continue;
+		lineRangesByCall.set(meta.call, readLineRanges(path));
+		const basePath = readBasePath(path);
+		const group = readsByBasePath.get(basePath);
+		if (group) group.push([index, meta]);
+		else readsByBasePath.set(basePath, [[index, meta]]);
+	}
+	for (const reads of readsByBasePath.values()) {
+		if (reads.length < 2) continue;
+		for (let earlier = 0; earlier < reads.length - 1; earlier++) {
+			const [index, meta] = reads[earlier];
+			for (let later = earlier + 1; later < reads.length; later++) {
+				if (readSupersedesRead(reads[later][1].call, meta.call, lineRangesByCall)) {
+					staleResultIndices.add(index);
+					break;
+				}
+			}
+		}
+	}
+
 	return { staleResultIndices };
 }
 export function pruneAssistantToolArguments(
@@ -596,6 +686,13 @@ function collectToolOutputPruneCandidates(
 	return { candidates, tokensSaved };
 }
 
+function minimumSavings(config: PruneConfig, options: PruneToolOutputsOptions = {}): number {
+	const relaxedMinimum = options.relaxedMinimum;
+	return typeof relaxedMinimum === "number" && Number.isFinite(relaxedMinimum)
+		? Math.min(config.minimumSavings, Math.max(0, relaxedMinimum))
+		: config.minimumSavings;
+}
+
 /**
  * Estimate the token savings {@link pruneToolOutputs} would achieve, without
  * mutating any entry. Returns 0 savings when below the configured minimum so the
@@ -604,9 +701,10 @@ function collectToolOutputPruneCandidates(
 export function estimateToolOutputPruneSavings(
 	entries: SessionEntry[],
 	config: PruneConfig = DEFAULT_PRUNE_CONFIG,
+	options: PruneToolOutputsOptions = {},
 ): { prunableCount: number; tokensSaved: number } {
 	const { candidates, tokensSaved } = collectToolOutputPruneCandidates(entries, config);
-	if (tokensSaved < config.minimumSavings || candidates.length === 0) {
+	if (tokensSaved < minimumSavings(config, options) || candidates.length === 0) {
 		return { prunableCount: 0, tokensSaved: 0 };
 	}
 	return { prunableCount: candidates.length, tokensSaved };
@@ -630,10 +728,20 @@ export function shouldRunMaintenancePrune(args: {
 	return args.estimatedSavings > args.cacheEpochResetCost;
 }
 
-export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig = DEFAULT_PRUNE_CONFIG): PruneResult {
+export interface PruneToolOutputsOptions {
+	/** Lower the usual minimum only when the caller is already over its compaction threshold. */
+	relaxedMinimum?: number;
+}
+
+export function pruneToolOutputs(
+	entries: SessionEntry[],
+	config: PruneConfig = DEFAULT_PRUNE_CONFIG,
+	options: PruneToolOutputsOptions = {},
+): PruneResult {
 	const { candidates, tokensSaved } = collectToolOutputPruneCandidates(entries, config);
+	const minimum = minimumSavings(config, options);
 
-	if (tokensSaved < config.minimumSavings || candidates.length === 0) {
+	if (tokensSaved < minimum || candidates.length === 0) {
 		return { prunedCount: 0, tokensSaved: 0, prunedEntries: [] };
 	}
 

package/src/proxy.ts

@@ -30,6 +30,33 @@ class ProxyMessageEventStream extends EventStream<AssistantMessageEvent, Assista
 	}
 }
 
+interface ReasoningBuffers {
+	summary: string;
+	raw: string;
+}
+
+const reasoningBuffers = new WeakMap<object, ReasoningBuffers>();
+
+function materializeReasoningProvenance(
+	content: Extract<AssistantMessage["content"][number], { type: "thinking" }>,
+): void {
+	const buffers = reasoningBuffers.get(content);
+	if (!buffers) return;
+	const mutable = content as { provenance?: "summary" | "raw" | "mixed"; summaryText?: string; rawText?: string };
+	if (mutable.provenance === undefined) {
+		if (mutable.summaryText === undefined && buffers.summary) mutable.summaryText = buffers.summary;
+		if (mutable.rawText === undefined && buffers.raw) mutable.rawText = buffers.raw;
+		mutable.provenance =
+			buffers.summary && buffers.raw ? "mixed" : buffers.summary ? "summary" : buffers.raw ? "raw" : undefined;
+	}
+	// Finalized display string must exclude raw CoT when a summary exists (parity with
+	// the Responses/Codex decoders): summary/mixed -> summary only; raw-only -> raw. The
+	// raw text stays available separately via rawText for explicit consumers.
+	const effSummary = mutable.summaryText ?? buffers.summary;
+	const effRaw = mutable.rawText ?? buffers.raw;
+	content.thinking = mutable.provenance === "raw" ? effRaw : effSummary || effRaw;
+}
+
 /**
  * Proxy event types - server sends these with partial field stripped to reduce bandwidth.
  */
@@ -41,6 +68,9 @@ export type ProxyAssistantMessageEvent =
 	| { type: "thinking_start"; contentIndex: number }
 	| { type: "thinking_delta"; contentIndex: number; delta: string }
 	| { type: "thinking_end"; contentIndex: number; contentSignature?: string }
+	| { type: "reasoning_summary_start"; contentIndex: number }
+	| { type: "reasoning_summary_delta"; contentIndex: number; delta: string }
+	| { type: "reasoning_summary_end"; contentIndex: number; content?: string }
 	| { type: "toolcall_start"; contentIndex: number; id: string; toolName: string }
 	| { type: "toolcall_delta"; contentIndex: number; delta: string }
 	| { type: "toolcall_end"; contentIndex: number }
@@ -238,14 +268,22 @@ function processProxyEvent(
 			throw new Error("Received text_end for non-text content");
 		}
 
-		case "thinking_start":
-			partial.content[proxyEvent.contentIndex] = { type: "thinking", thinking: "" };
+		case "thinking_start": {
+			const content = { type: "thinking", thinking: "" } as Extract<
+				AssistantMessage["content"][number],
+				{ type: "thinking" }
+			>;
+			partial.content[proxyEvent.contentIndex] = content;
+			reasoningBuffers.set(content, { summary: "", raw: "" });
 			return { type: "thinking_start", contentIndex: proxyEvent.contentIndex, partial };
+		}
 
 		case "thinking_delta": {
 			const content = partial.content[proxyEvent.contentIndex];
 			if (content?.type === "thinking") {
 				content.thinking += proxyEvent.delta;
+				const buffers = reasoningBuffers.get(content);
+				if (buffers) buffers.raw += proxyEvent.delta;
 				return {
 					type: "thinking_delta",
 					contentIndex: proxyEvent.contentIndex,
@@ -256,10 +294,52 @@ function processProxyEvent(
 			throw new Error("Received thinking_delta for non-thinking content");
 		}
 
+		case "reasoning_summary_start":
+			return { type: "reasoning_summary_start", contentIndex: proxyEvent.contentIndex, partial };
+
+		case "reasoning_summary_delta": {
+			const content = partial.content[proxyEvent.contentIndex];
+			if (content?.type === "thinking") {
+				content.thinking += proxyEvent.delta;
+				const buffers = reasoningBuffers.get(content);
+				if (buffers) buffers.summary += proxyEvent.delta;
+				return {
+					type: "reasoning_summary_delta",
+					contentIndex: proxyEvent.contentIndex,
+					delta: proxyEvent.delta,
+					partial,
+				};
+			}
+			throw new Error("Received reasoning_summary_delta for non-thinking content");
+		}
+
+		case "reasoning_summary_end": {
+			const content = partial.content[proxyEvent.contentIndex];
+			if (content?.type === "thinking") {
+				const buffers = reasoningBuffers.get(content);
+				// Final-only summaries arrive with the text on the end event and no summary
+				// deltas, so the accumulated buffer is empty. Prefer the end event's content
+				// so the summary survives the proxy and materializes as provenance "summary".
+				if (buffers && !buffers.summary.trim() && proxyEvent.content) {
+					buffers.summary = proxyEvent.content;
+					if (!content.thinking.trim()) content.thinking = proxyEvent.content;
+				}
+				materializeReasoningProvenance(content);
+				return {
+					type: "reasoning_summary_end",
+					contentIndex: proxyEvent.contentIndex,
+					content: buffers?.summary || proxyEvent.content || "",
+					partial,
+				};
+			}
+			throw new Error("Received reasoning_summary_end for non-thinking content");
+		}
+
 		case "thinking_end": {
 			const content = partial.content[proxyEvent.contentIndex];
 			if (content?.type === "thinking") {
 				content.thinkingSignature = proxyEvent.contentSignature;
+				materializeReasoningProvenance(content);
 				return {
 					type: "thinking_end",
 					contentIndex: proxyEvent.contentIndex,

package/src/types.ts

@@ -13,6 +13,7 @@ import type {
 	Tool,
 	ToolChoice,
 	ToolResultMessage,
+	TransportFailureFacts,
 	TSchema,
 } from "@gajae-code/ai";
 import type { AppendOnlyContextManager } from "./append-only-context";
@@ -58,6 +59,7 @@ export type ManagedAttemptContinuation = (ownership: ManagedAttemptContinuationO
 /** Decision returned by managed fallback policy for one provisional attempt. */
 export type ManagedAttemptDecision =
 	| { type: "retry"; continuation: ManagedAttemptContinuation }
+	| { type: "maintenance"; continuation: ManagedAttemptContinuation }
 	| { type: "terminal"; terminal: RunTerminalRequest };
 
 /** Structured result for one managed upstream invocation. */
@@ -67,9 +69,10 @@ export type ManagedAttemptOutcome =
 			failure: {
 				message: AssistantMessage;
 				/** Exact provider transport facts, including retry headers, for fallback policy. */
-				transportFailure?: import("@gajae-code/ai").TransportFailureFacts;
+				transportFailure?: TransportFailureFacts;
 			};
 	  }
+	| { type: "context_overflow_discarded"; message: AssistantMessage }
 	| { type: "run_terminal"; reason: "cancelled" | "error" | "exhausted" };
 
 export type ManagedAttemptOutcomeHandler = (