@gajae-code/agent-core 0.10.1 → 0.11.0

package/src/agent.ts

@@ -20,6 +20,7 @@ import {
 	type ToolChoice,
 	type ToolResultMessage,
 } from "@gajae-code/ai";
+import { extractHttpStatusFromError } from "@gajae-code/utils";
 import { agentLoop, agentLoopContinue } from "./agent-loop";
 import type { AppendOnlyContextManager } from "./append-only-context";
 import type { HarmonyAuditEvent } from "./harmony-leak";
@@ -32,6 +33,12 @@ import type {
 	AgentState,
 	AgentTool,
 	AgentToolContext,
+	ManagedAttemptContinuation,
+	ManagedAttemptContinuationOwnership,
+	ManagedAttemptDecision,
+	ManagedAttemptOutcome,
+	ManagedLogicalRunId,
+	RunTerminalRequest,
 	StreamFn,
 	ToolCallContext,
 } from "./types";
@@ -88,6 +95,13 @@ function refreshToolChoiceForActiveTools(
 	return tools.some(tool => tool.name === toolName) ? toolChoice : undefined;
 }
 
+export class ManagedCursorInvariantError extends Error {
+	constructor(message: string = "Managed Cursor attempt received a provider-side tool result") {
+		super(message);
+		this.name = "ManagedCursorInvariantError";
+	}
+}
+
 export class AgentBusyError extends Error {
 	constructor(
 		message: string = "Agent is already processing. Use steer() or followUp() to queue messages, or wait for completion.",
@@ -276,6 +290,16 @@ export interface AgentOptions {
 
 export interface AgentPromptOptions {
 	toolChoice?: ToolChoice;
+	/** Disable transport replay; fallback accounting is owned by the caller. */
+	fallbackManaged?: boolean;
+	/** Called synchronously after this invocation claims the agent run, before asynchronous provider work. */
+	onRunAccepted?: () => void;
+	/** Called once immediately before every managed upstream request. */
+	nextFallbackAttempt?: AgentLoopConfig["nextFallbackAttempt"];
+	/** Called after a managed upstream request is accepted and committed. */
+	onManagedAttemptAccepted?: AgentLoopConfig["onManagedAttemptAccepted"];
+	/** Receives a discarded managed attempt without exposing assistant lifecycle events. */
+	onManagedAttemptOutcome?: AgentLoopConfig["onManagedAttemptOutcome"];
 }
 
 /** Buffered Cursor tool result with text position at time of call */
@@ -332,6 +356,8 @@ export class Agent {
 	#resolveRunningPrompt?: () => void;
 	#runSequence = 0;
 	#activeRunId?: number;
+	#continuationGeneration = 0;
+	#activeFallbackManaged = false;
 	#kimiApiFormat?: "openai" | "anthropic";
 	#preferWebsockets?: boolean;
 	#transformToolCallArguments?: (args: Record<string, unknown>, toolName: string) => Record<string, unknown>;
@@ -345,6 +371,7 @@ export class Agent {
 	#onHarmonyLeak?: (event: HarmonyAuditEvent) => void | Promise<void>;
 	#onBeforeYield?: () => Promise<void> | void;
 	#shouldPause?: AgentLoopConfig["shouldPause"];
+	#maintainContext?: AgentLoopConfig["maintainContext"];
 	#telemetry?: AgentLoopConfig["telemetry"];
 	#appendOnlyContext?: AppendOnlyContextManager;
 
@@ -354,6 +381,8 @@ export class Agent {
 
 	/** Buffered Cursor tool results with text length at time of call (for correct ordering) */
 	#cursorToolResultBuffer: CursorToolResultEntry[] = [];
+	#terminalizedLogicalRunIds = new Set<ManagedLogicalRunId>();
+	#managedLogicalRunOwner?: ManagedLogicalRunId;
 
 	streamFn: StreamFn;
 	getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
@@ -680,6 +709,10 @@ export class Agent {
 		this.#shouldPause = fn;
 	}
 
+	setMaintainContext(fn: AgentLoopConfig["maintainContext"] | undefined): void {
+		this.#maintainContext = fn;
+	}
+
 	emitExternalEvent(event: AgentEvent) {
 		switch (event.type) {
 			case "message_start":
@@ -830,7 +863,7 @@ export class Agent {
 		this.#contextRevision++;
 	}
 
-	setModel(m: Model) {
+	setModel(m: Model | undefined) {
 		this.#state.model = m;
 		this.#contextRevision++;
 	}
@@ -1088,23 +1121,30 @@ export class Agent {
 	 * #runLoop guards every state mutation with a run id.
 	 */
 	forceAbort(reason = "Force aborted"): boolean {
-		const hadActiveRun = this.#runningPrompt !== undefined || this.#state.isStreaming;
+		const runId = this.#activeRunId;
+		const managedLogicalRunId = this.#managedLogicalRunOwner;
+		const hadActiveRun = runId !== undefined && (this.#runningPrompt !== undefined || this.#state.isStreaming);
 		if (!hadActiveRun) return false;
 
 		this.#abortController?.abort(reason);
-		this.#activeRunId = undefined;
+		this.#continuationGeneration++;
 		this.#state.isStreaming = false;
 		this.#state.streamMessage = null;
 		this.#state.pendingToolCalls = new Set<string>();
 		this.#abortController = undefined;
 		this.#cursorToolResultBuffer = [];
+		this.#managedLogicalRunOwner = undefined;
 
 		const resolve = this.#resolveRunningPrompt;
 		this.#runningPrompt = undefined;
 		this.#resolveRunningPrompt = undefined;
+		this.#activeRunId = undefined;
 		resolve?.();
-
-		this.#emit({ type: "agent_end", messages: [] });
+		if (this.#activeFallbackManaged) {
+			this.requestRunTerminal(managedLogicalRunId ?? runId, { stopReason: "cancelled" });
+		} else {
+			this.#finalizeRun(runId, { type: "agent_end", messages: [] });
+		}
 		return true;
 	}
 
@@ -1112,12 +1152,56 @@ export class Agent {
 		return this.#runningPrompt ?? Promise.resolve();
 	}
 
+	/** The active per-attempt run identifier. */
+	get activeRunId(): number | undefined {
+		return this.#activeRunId;
+	}
+
+	/**
+	 * Stable identifier for the active managed logical run, shared by every retry
+	 * attempt. Pass this value to requestRunTerminal(); never retain activeRunId
+	 * for managed terminal completion.
+	 */
+	get currentManagedLogicalRunId(): ManagedLogicalRunId | undefined {
+		return this.#managedLogicalRunOwner;
+	}
+
+	/**
+	 * Request terminal completion through the single logical-run keyed finalizer.
+	 *
+	 * For managed runs, logicalRunId must be currentManagedLogicalRunId from any
+	 * attempt in the retry chain. Non-managed runs use their activeRunId. Terminal
+	 * requests with messages emit a committed message_start/message_end lifecycle
+	 * for each diagnostic before agent_end. Requests without messages (such as
+	 * cancellation) emit only agent_end.
+	 */
+	requestRunTerminal(logicalRunId: ManagedLogicalRunId, request: RunTerminalRequest): boolean {
+		if (this.#terminalizedLogicalRunIds.has(logicalRunId)) return false;
+		this.#finalizeRun(
+			logicalRunId,
+			{
+				type: "agent_end",
+				messages: request.messages ?? [],
+				...(request.stopReason === "cancelled" ? { stopReason: "cancelled" as const } : {}),
+			},
+			() => {
+				for (const message of request.messages ?? []) {
+					this.#emit({ type: "message_start", message });
+					this.appendMessage(message);
+					this.#emit({ type: "message_end", message });
+				}
+			},
+		);
+		return true;
+	}
+
 	reset() {
 		this.#state.messages = [];
 		this.#contextRevision++;
 		this.#state.isStreaming = false;
 		this.#state.streamMessage = null;
 		this.#state.pendingToolCalls = new Set<string>();
+		this.#managedLogicalRunOwner = undefined;
 		this.#state.error = undefined;
 		this.#steeringQueue = [];
 		this.#followUpQueue = [];
@@ -1170,6 +1254,10 @@ export class Agent {
 		}
 
 		assertUserImagePlaceholdersHavePayload(msgs);
+		if (this.#managedLogicalRunOwner !== undefined) {
+			this.requestRunTerminal(this.#managedLogicalRunOwner, { stopReason: "cancelled" });
+			this.#managedLogicalRunOwner = undefined;
+		}
 
 		await this.#runLoop(msgs, promptOptions);
 	}
@@ -1177,7 +1265,7 @@ export class Agent {
 	/**
 	 * Continue from current context (used for retries and resuming queued messages).
 	 */
-	async continue() {
+	async continue(options?: AgentPromptOptions) {
 		if (this.#state.isStreaming) {
 			throw new AgentBusyError();
 		}
@@ -1189,13 +1277,13 @@ export class Agent {
 		if (messages[messages.length - 1].role === "assistant") {
 			const queuedSteering = this.#dequeueSteeringMessages();
 			if (queuedSteering.length > 0) {
-				await this.#runLoop(queuedSteering, { skipInitialSteeringPoll: true });
+				await this.#runLoop(queuedSteering, { ...options, skipInitialSteeringPoll: true });
 				return;
 			}
 
 			const queuedFollowUp = this.#dequeueFollowUpMessages();
 			if (queuedFollowUp.length > 0) {
-				await this.#runLoop(queuedFollowUp);
+				await this.#runLoop(queuedFollowUp, options);
 				return;
 			}
 
@@ -1206,7 +1294,7 @@ export class Agent {
 			throw new Error("No messages to continue from");
 		}
 
-		await this.#runLoop(undefined);
+		await this.#runLoop(undefined, options);
 	}
 
 	/**
@@ -1225,18 +1313,41 @@ export class Agent {
 		this.#resolveRunningPrompt = resolve;
 
 		const runId = ++this.#runSequence;
+		const continuationGeneration = ++this.#continuationGeneration;
 		this.#activeRunId = runId;
 		const abortController = new AbortController();
 		this.#abortController = abortController;
 		this.#state.isStreaming = true;
 		this.#state.streamMessage = null;
 		this.#state.error = undefined;
-
-		// Clear Cursor tool result buffer at start of each run
+		options?.onRunAccepted?.();
+
+		const fallbackManaged = options?.fallbackManaged === true;
+		const managedLogicalRunOwner = fallbackManaged ? (this.#managedLogicalRunOwner ?? runId) : undefined;
+		const startsManagedLogicalRun = fallbackManaged && this.#managedLogicalRunOwner === undefined;
+		if (startsManagedLogicalRun) {
+			this.#managedLogicalRunOwner = managedLogicalRunOwner;
+			this.#emit({ type: "agent_start" });
+		}
+		if (fallbackManaged && this.#cursorToolResultBuffer.length > 0) {
+			const error = new ManagedCursorInvariantError(
+				"Managed Cursor attempt started with buffered provider-side tool results",
+			);
+			this.#state.isStreaming = false;
+			this.#abortController = undefined;
+			this.#activeRunId = undefined;
+			this.#runningPrompt = undefined;
+			this.#resolveRunningPrompt = undefined;
+			resolve();
+			this.requestRunTerminal(managedLogicalRunOwner ?? runId, { stopReason: "error" });
+			this.#managedLogicalRunOwner = undefined;
+			throw error;
+		}
+		// Each run gets a fresh buffer only after managed stale-state validation.
 		this.#cursorToolResultBuffer = [];
+		this.#activeFallbackManaged = fallbackManaged;
 
 		const reasoning = this.#state.thinkingLevel;
-
 		const context: AgentContext = {
 			systemPrompt: this.#state.systemPrompt,
 			messages: this.#state.messages.slice(),
@@ -1244,7 +1355,7 @@ export class Agent {
 		};
 
 		const cursorOnToolResult =
-			this.#cursorExecHandlers || this.#cursorOnToolResult
+			!fallbackManaged && (this.#cursorExecHandlers || this.#cursorOnToolResult)
 				? async (message: ToolResultMessage) => {
 						let finalMessage = message;
 						if (this.#activeRunId !== runId) {
@@ -1261,7 +1372,6 @@ export class Agent {
 								}
 							} catch {}
 						}
-						// Buffer tool result with current text length for correct ordering later.
 						// Cursor executes tools server-side during streaming, so the assistant message
 						// already incorporates results. We buffer here and emit in correct order
 						// when the assistant message ends.
@@ -1273,7 +1383,10 @@ export class Agent {
 
 		const getToolChoice = () =>
 			this.#getToolChoice?.() ?? refreshToolChoiceForActiveTools(options?.toolChoice, this.#state.tools);
-		const cursorExecHandlers = this.#cursorExecHandlersForRun(runId);
+		const cursorExecHandlers = fallbackManaged ? undefined : this.#cursorExecHandlersForRun(runId);
+		let managedDecision: ManagedAttemptDecision | undefined;
+		let managedOutcome: ManagedAttemptOutcome | undefined;
+		let maintenanceInterrupted = false;
 
 		const config: AgentLoopConfig = {
 			model,
@@ -1296,6 +1409,21 @@ export class Agent {
 			maxRetryDelayMs: this.#maxRetryDelayMs,
 			requestMaxRetries: this.#requestMaxRetries,
 			streamMaxRetries: this.#streamMaxRetries,
+			...(fallbackManaged
+				? {
+						fallbackManaged: true,
+						nextFallbackAttempt: options?.nextFallbackAttempt,
+						onManagedAttemptAccepted: options?.onManagedAttemptAccepted,
+						onManagedAttemptOutcome: async outcome => {
+							managedOutcome = outcome;
+							managedDecision = (await options?.onManagedAttemptOutcome?.(outcome)) ?? {
+								type: "terminal",
+								terminal: { stopReason: outcome.type === "run_terminal" ? outcome.reason : "error" },
+							};
+							return managedDecision;
+						},
+					}
+				: {}),
 			kimiApiFormat: this.#kimiApiFormat,
 			preferWebsockets: this.#preferWebsockets,
 			convertToLlm: this.#convertToLlm,
@@ -1314,8 +1442,8 @@ export class Agent {
 				context.systemPrompt = this.#state.systemPrompt;
 				context.tools = this.#state.tools;
 			},
-			cursorExecHandlers,
-			cursorOnToolResult,
+			...(cursorExecHandlers ? { cursorExecHandlers } : {}),
+			...(cursorOnToolResult ? { cursorOnToolResult } : {}),
 			transformToolCallArguments: this.#transformToolCallArguments,
 			intentTracing: this.#intentTracing,
 			appendOnlyContext: this.#appendOnlyContext,
@@ -1384,6 +1512,12 @@ export class Agent {
 				if (this.#activeRunId !== runId) return false;
 				return this.#shouldPause?.() === true;
 			},
+			maintainContext: this.#maintainContext
+				? async (context, lifecycle) => {
+						if (this.#activeRunId !== runId) return "not-needed";
+						return (await this.#maintainContext?.(context, lifecycle)) ?? "not-needed";
+					}
+				: undefined,
 			telemetry: this.#telemetry,
 		};
 
@@ -1391,8 +1525,8 @@ export class Agent {
 
 		try {
 			const stream = messages
-				? agentLoop(messages, context, config, abortController.signal, this.streamFn)
-				: agentLoopContinue(context, config, abortController.signal, this.streamFn);
+				? agentLoop(messages, context, config, abortController.signal, this.streamFn, !fallbackManaged)
+				: agentLoopContinue(context, config, abortController.signal, this.streamFn, !fallbackManaged);
 
 			for await (const event of stream) {
 				if (this.#activeRunId !== runId) {
@@ -1412,6 +1546,9 @@ export class Agent {
 						break;
 
 					case "message_end":
+						if (fallbackManaged && this.#cursorToolResultBuffer.length > 0) {
+							throw new ManagedCursorInvariantError();
+						}
 						partial = null;
 						// Check if this is an assistant message with buffered Cursor tool results.
 						// If so, split the message to emit tool results at the correct position.
@@ -1444,9 +1581,18 @@ export class Agent {
 						break;
 
 					case "agent_end":
+						if (fallbackManaged && managedOutcome) {
+							continue;
+						}
 						this.#state.isStreaming = false;
 						this.#state.streamMessage = null;
-						break;
+						if (event.stopReason === "maintenance") {
+							maintenanceInterrupted = true;
+							this.#emit(event);
+							continue;
+						}
+						this.#finalizeRun(managedLogicalRunOwner ?? runId, event);
+						continue;
 				}
 
 				// Emit to listeners
@@ -1456,6 +1602,15 @@ export class Agent {
 			if (this.#activeRunId !== runId) {
 				return;
 			}
+			if (managedOutcome) {
+				if (managedDecision?.type === "terminal") {
+					this.requestRunTerminal(managedLogicalRunOwner ?? runId, managedDecision.terminal);
+				} else if (managedOutcome.type === "run_terminal") {
+					this.requestRunTerminal(managedLogicalRunOwner ?? runId, { stopReason: managedOutcome.reason });
+				} else if (managedDecision?.type !== "retry") {
+					this.#finalizeRun(managedLogicalRunOwner ?? runId);
+				}
+			}
 
 			// Handle any remaining partial message
 			if (partial && partial.role === "assistant" && Array.isArray(partial.content) && partial.content.length > 0) {
@@ -1494,23 +1649,59 @@ export class Agent {
 				},
 				stopReason: abortController.signal.aborted ? "aborted" : "error",
 				errorMessage: err?.message || String(err),
+				errorStatus: extractHttpStatusFromError({ status: err?.errorStatus }) ?? extractHttpStatusFromError(err),
 				timestamp: Date.now(),
 			} as AgentMessage;
 
-			this.appendMessage(errorMsg);
 			this.#state.error = err?.message || String(err);
-			this.#emit({ type: "agent_end", messages: [errorMsg] });
+			this.requestRunTerminal(managedLogicalRunOwner ?? runId, {
+				stopReason: abortController.signal.aborted ? "cancelled" : "error",
+				messages: [errorMsg],
+			});
 		} finally {
+			let continuation: ManagedAttemptContinuation | undefined;
+			if (managedOutcome?.type === "retryable_discarded" && managedDecision?.type === "retry") {
+				continuation = managedDecision.continuation;
+			}
+			const ownership: ManagedAttemptContinuationOwnership = {
+				runId,
+				logicalRunId: managedLogicalRunOwner ?? runId,
+				generation: continuationGeneration,
+				isCurrent: () => this.#continuationGeneration === continuationGeneration && this.#activeRunId === undefined,
+			};
 			if (this.#activeRunId === runId) {
 				this.#state.isStreaming = false;
 				this.#state.streamMessage = null;
 				this.#state.pendingToolCalls = new Set<string>();
 				this.#abortController = undefined;
 				this.#activeRunId = undefined;
+				this.#activeFallbackManaged = false;
 				this.#resolveRunningPrompt?.();
 				this.#runningPrompt = undefined;
 				this.#resolveRunningPrompt = undefined;
 			}
+			if (
+				fallbackManaged &&
+				!continuation &&
+				!maintenanceInterrupted &&
+				this.#managedLogicalRunOwner === managedLogicalRunOwner
+			) {
+				this.#managedLogicalRunOwner = undefined;
+			}
+			if (continuation && ownership.isCurrent()) {
+				try {
+					await continuation(ownership);
+					if (this.#activeRunId === undefined && this.#managedLogicalRunOwner === managedLogicalRunOwner) {
+						this.#managedLogicalRunOwner = undefined;
+					}
+				} catch (err) {
+					if (ownership.isCurrent()) {
+						this.#state.error = err instanceof Error ? err.message : String(err);
+						this.requestRunTerminal(managedLogicalRunOwner ?? runId, { stopReason: "error" });
+						if (this.#managedLogicalRunOwner === managedLogicalRunOwner) this.#managedLogicalRunOwner = undefined;
+					}
+				}
+			}
 		}
 	}
 
@@ -1521,6 +1712,20 @@ export class Agent {
 	}
 
 	/** Calculate total text length from an assistant message's content blocks */
+	#finalizeRun(
+		logicalRunId: ManagedLogicalRunId,
+		event?: Extract<AgentEvent, { type: "agent_end" }>,
+		beforeEvent?: () => void,
+	): void {
+		if (this.#terminalizedLogicalRunIds.has(logicalRunId)) return;
+		this.#terminalizedLogicalRunIds.add(logicalRunId);
+		if (this.#terminalizedLogicalRunIds.size > 256) {
+			this.#terminalizedLogicalRunIds.delete(this.#terminalizedLogicalRunIds.values().next().value!);
+		}
+		beforeEvent?.();
+		if (event) this.#emit(event);
+	}
+
 	#getAssistantTextLength(message: AgentMessage | null): number {
 		if (message?.role !== "assistant" || !Array.isArray(message.content)) {
 			return 0;

package/src/compaction/entries.ts

@@ -115,6 +115,17 @@ export interface ModeChangeEntry extends SessionEntryBase {
 	data?: Record<string, unknown>;
 }
 
+export interface ConfiguredModelChainEntry extends SessionEntryBase {
+	type: "configured_model_chain";
+	role: string;
+	entries: readonly string[];
+	origin: string;
+	identity?: string;
+	explicitHead: boolean;
+	/** Whether this entry removes the configured chain for its role. */
+	cleared?: boolean;
+}
+
 export interface CustomCompactionSessionEntries {}
 
 export type SessionEntry =
@@ -131,6 +142,7 @@ export type SessionEntry =
 	| MCPToolSelectionEntry
 	| SessionInitEntry
 	| ModeChangeEntry
+	| ConfiguredModelChainEntry
 	| CustomCompactionSessionEntries[keyof CustomCompactionSessionEntries];
 
 export interface ReadonlySessionManager {

package/src/compaction/openai.ts

@@ -24,6 +24,8 @@ import type { AssistantMessage, Message, Model } from "@gajae-code/ai/types";
 import {
 	getOpenAIResponsesHistoryItems,
 	getOpenAIResponsesHistoryPayload,
+	neutralizeReservedControlTokens,
+	neutralizeResponsesInputControlTokens,
 	normalizeResponsesToolCallId,
 } from "@gajae-code/ai/utils";
 import { $env, logger } from "@gajae-code/utils";
@@ -479,10 +481,12 @@ export async function requestOpenAiRemoteCompaction(
 	const endpoint = resolveOpenAiCompactEndpoint(model, options?.authCredentialType);
 	const request: OpenAiRemoteCompactionRequest = {
 		model: model.id,
-		input: trimOpenAiCompactInput(
-			compactInput,
-			resolveOpenAiCompactInputBudget(model.contextWindow, model.maxTokens),
-			instructions,
+		input: neutralizeResponsesInputControlTokens(
+			trimOpenAiCompactInput(
+				compactInput,
+				resolveOpenAiCompactInputBudget(model.contextWindow, model.maxTokens),
+				instructions,
+			),
 		),
 		instructions,
 	};
@@ -553,10 +557,17 @@ export async function requestRemoteCompaction(
 	request: RemoteCompactionRequest,
 	signal?: AbortSignal,
 ): Promise<RemoteCompactionResponse> {
+	// The prompt embeds the serialized transcript, which can carry leaked Harmony
+	// control-token markers (e.g. `<|channel|>analysis`) from model output; a
+	// gpt-5.6-backed summarization endpoint rejects those with `Request blocked`.
+	const sanitizedRequest: RemoteCompactionRequest = {
+		systemPrompt: neutralizeReservedControlTokens(request.systemPrompt),
+		prompt: neutralizeReservedControlTokens(request.prompt),
+	};
 	const response = await fetch(endpoint, {
 		method: "POST",
 		headers: { "content-type": "application/json" },
-		body: JSON.stringify(request),
+		body: JSON.stringify(sanitizedRequest),
 		signal,
 	});
 

package/src/types.ts

@@ -25,11 +25,82 @@ export type StreamFn = (
 	...args: Parameters<typeof streamSimple>
 ) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>;
 
+/** Stable identifier for a managed logical run, shared by all of its retry attempts. */
+export type ManagedLogicalRunId = number;
+
+/** Terminal completion requested for a logical run. */
+export interface RunTerminalRequest {
+	stopReason: "cancelled" | "error" | "exhausted";
+	messages?: AgentMessage[];
+}
+
+/**
+ * Ownership token supplied when Agent invokes a retry continuation.
+ *
+ * A continuation MUST verify `isCurrent()` immediately before starting a
+ * follow-up invocation and abandon the retry when it returns false. The token
+ * becomes invalid when its originating run is force-aborted or superseded.
+ * Coding-agent retry continuations must accept this argument and must not call
+ * `agent.continue()` after ownership has been lost.
+ */
+export interface ManagedAttemptContinuationOwnership {
+	/** Per-attempt run-loop id; use only for attempt-local ownership checks. */
+	readonly runId: number;
+	/** Stable managed logical-run id; use for all terminal completion requests. */
+	readonly logicalRunId: ManagedLogicalRunId;
+	readonly generation: number;
+	isCurrent(): boolean;
+}
+
+/** Runs after a discarded attempt is idle, only while its ownership token remains current. */
+export type ManagedAttemptContinuation = (ownership: ManagedAttemptContinuationOwnership) => void | Promise<void>;
+
+/** Decision returned by managed fallback policy for one provisional attempt. */
+export type ManagedAttemptDecision =
+	| { type: "retry"; continuation: ManagedAttemptContinuation }
+	| { type: "terminal"; terminal: RunTerminalRequest };
+
+/** Structured result for one managed upstream invocation. */
+export type ManagedAttemptOutcome =
+	| {
+			type: "retryable_discarded";
+			failure: {
+				message: AssistantMessage;
+				/** Exact provider transport facts, including retry headers, for fallback policy. */
+				transportFailure?: import("@gajae-code/ai").TransportFailureFacts;
+			};
+	  }
+	| { type: "run_terminal"; reason: "cancelled" | "error" | "exhausted" };
+
+export type ManagedAttemptOutcomeHandler = (
+	outcome: ManagedAttemptOutcome,
+) => ManagedAttemptDecision | Promise<ManagedAttemptDecision>;
+
+/**
+ * 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.
+ */
+export type MidRunMaintenanceOutcome = "not-needed" | "pruned" | "compacted" | "promoted" | "failed" | "aborted";
+
 /**
  * Configuration for the agent loop.
  */
 export interface AgentLoopConfig extends SimpleStreamOptions {
 	model: Model;
+	/**
+	 * Supplies a fresh opaque token at each concrete managed transport invocation.
+	 * The callback runs at the stream boundary so controller accounting matches
+	 * upstream request count, including multi-step tool turns.
+	 */
+	nextFallbackAttempt?: (model: Model) => SimpleStreamOptions["fallbackAttempt"];
+	/** Called after a managed upstream request is accepted and committed. */
+	onManagedAttemptAccepted?: () => void | Promise<void>;
+
+	/** Receives a managed invocation outcome without publishing provisional lifecycle events. */
+	onManagedAttemptOutcome?: ManagedAttemptOutcomeHandler;
 
 	/**
 	 * When to interrupt tool execution for steering messages.
@@ -161,6 +232,33 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 */
 	syncContextBeforeModelCall?: (context: AgentContext) => void | Promise<void>;
 
+	/**
+	 * Cooperative mid-run context-maintenance checkpoint.
+	 *
+	 * Invoked at the top of every loop iteration AFTER pending tool-result /
+	 * steering messages have been materialized into durable context and BEFORE
+	 * {@link syncContextBeforeModelCall} and the model call. This is the only
+	 * boundary where the full unsent context (tool results + dequeued steering)
+	 * is already durable, so a long uninterrupted tool loop can be bounded here
+	 * before it grows past the provider window.
+	 *
+	 * The callback owns the maintenance decision (prune / compact / promote) and
+	 * receives the minimal cancellation-aware lifecycle: `signal` is the
+	 * 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.
+	 */
+	maintainContext?: (
+		context: AgentContext,
+		lifecycle: {
+			signal: AbortSignal;
+			awaitEventDrain: (invocationSignal: AbortSignal) => Promise<void>;
+		},
+	) => Promise<MidRunMaintenanceOutcome> | MidRunMaintenanceOutcome;
+
 	/**
 	 * Optional transform applied to tool call arguments before execution.
 	 * Use for deobfuscating secrets or rewriting arguments.
@@ -357,7 +455,7 @@ export type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessag
  */
 export interface AgentState {
 	systemPrompt: string[];
-	model: Model;
+	model: Model | undefined;
 	thinkingLevel?: Effort;
 	tools: AgentTool<any>[];
 	messages: AgentMessage[]; // Can include attachments + custom message types
@@ -470,8 +568,10 @@ export type AgentEvent =
 	| {
 			type: "agent_end";
 			messages: AgentMessage[];
-			/** Indicates whether the loop ended normally or suspended at a pause checkpoint. */
-			stopReason?: "completed" | "paused";
+			/** Indicates whether the loop ended normally, suspended, cancelled, or entered maintenance. */
+			stopReason?: "completed" | "paused" | "cancelled" | "maintenance";
+			/** Present iff `stopReason === "maintenance"`; the maintenance outcome. */
+			maintenanceOutcome?: MidRunMaintenanceOutcome;
 			/** Present iff `AgentTelemetryConfig` was supplied on this run. */
 			telemetry?: AgentRunSummary;
 			coverage?: AgentRunCoverage;