@sayknow-cli/agent-core 0.3.16 → 0.4.0

package/src/agent-loop.ts

@@ -2,19 +2,24 @@
  * Agent loop that works with AgentMessage throughout.
  * Transforms to Message[] only at the LLM call boundary.
  */
+
+import { types as nodeUtilTypes } from "node:util";
 import {
 	type AssistantMessage,
 	type AssistantMessageEvent,
 	type Context,
+	classifyContextOverflow,
+	classifyFallbackTrigger,
 	EventStream,
-	isContextOverflow,
 	isZodSchema,
 	streamSimple,
 	type ToolResultMessage,
 	type TSchema,
+	transportFailureFacts,
 	validateToolArguments,
 	zodToWireSchema,
 } from "@sayknow-cli/ai";
+import { isInvalidPromptError, neutralizeReservedControlTokens } from "@sayknow-cli/ai/utils";
 import { sanitizeText } from "@sayknow-cli/utils";
 import {
 	createHarmonyAuditEvent,
@@ -51,19 +56,160 @@ import type {
 	AgentMessage,
 	AgentTool,
 	AgentToolResult,
+	ManagedAttemptOutcome,
 	StreamFn,
 } from "./types";
 
 /** Sentinel returned by the abort race in `streamAssistantResponse`. */
+/**
+ * Defensive caps for a provisional managed attempt. These are intentionally
+ * well above ordinary streamed responses; they only bound memory when an
+ * upstream emits an unbounded event stream before the attempt can commit.
+ */
+export const MANAGED_ATTEMPT_MAX_STAGED_EVENTS = 10_000;
+export const MANAGED_ATTEMPT_MAX_STAGED_BYTES = 16 * 1024 * 1024;
+
+/**
+ * Local staging failure: the provisional buffer limit was exceeded. Carries
+ * NO transport facts or status by design — only original typed provider
+ * transport facts may authorize provider fallback, so local buffer machinery
+ * must never masquerade as provider evidence or consume the fallback chain.
+ * It is therefore non-retryable and surfaces as an explicit local error.
+ */
+class ManagedAttemptBufferOverflowError extends Error {
+	constructor() {
+		super("Managed fallback attempt exceeded the provisional event buffer limit");
+		this.name = "ManagedAttemptBufferOverflowError";
+	}
+}
+
+/**
+ * Local snapshot-machinery failure. Deliberately carries no transport facts
+ * or status, so managed fallback classification never treats it as a provider
+ * retry trigger — it fails fast instead of burning the fallback chain.
+ */
+class ManagedAttemptSnapshotError extends Error {
+	constructor() {
+		super(
+			"Managed fallback attempt could not produce a serializable event snapshot (local snapshot bug, not a provider failure)",
+		);
+		this.name = "ManagedAttemptSnapshotError";
+	}
+}
+
+const managedAttemptTextEncoder = new TextEncoder();
+
 const ABORTED: unique symbol = Symbol("agent-loop-aborted");
+function managedContextOverflow(message: AssistantMessage, config: AgentLoopConfig): boolean {
+	const transportFailure = managedTransportFailure(message);
+	// Managed empty-stop responses may be repaired by the managed shell below; only
+	// typed/error overflows are discardable before that normalization boundary.
+	if (config.fallbackManaged && message.stopReason !== "error") return false;
+	return classifyContextOverflow(message, transportFailure, config.model.contextWindow);
+}
+
+/** Managed fallback owns retry policy; only attached typed transport facts may discard an attempt. */
+function managedProperty(value: unknown, key: string): unknown {
+	if (!value || typeof value !== "object") return undefined;
+	try {
+		return Reflect.get(value, key);
+	} catch {
+		return undefined;
+	}
+}
+
+function managedTransportFailure(failure: unknown) {
+	const facts = managedProperty(failure, "transportFailure");
+	return facts && typeof facts === "object" ? transportFailureFacts(facts) : undefined;
+}
+
+function managedRetryableFailure(failure: unknown): boolean {
+	const facts = managedTransportFailure(failure);
+	if (!facts) return false;
+	const trigger = classifyFallbackTrigger(facts);
+	return (
+		trigger.class === "rate_limit" ||
+		trigger.class === "quota" ||
+		trigger.class === "auth" ||
+		trigger.class === "server"
+	);
+}
+
 /**
- * Detect empty "successful" responses that indicate a proxy-level context
- * overflow (e.g. LiteLLM returning `content: []`, `stopReason: "stop"`, and a
- * fabricated near-zero usage). We delegate to {@link isContextOverflow} which
- * has the threshold constant, so the detection logic stays in one place.
+ * Neutralize leaked reserved control tokens in-place across the outgoing
+ * history so a re-send no longer carries the poison that triggered
+ * `Request blocked (code=invalid_prompt)`. Only string text fields are
+ * rewritten; no history item is ever dropped or reordered. Returns whether any
+ * byte actually changed — the circuit breaker uses this to decide between a
+ * single repaired resend (changed) and immediate fail-fast (unchanged).
  */
-function isEmptyResponseOverflow(message: AssistantMessage): boolean {
-	return isContextOverflow(message);
+function repairInvalidPromptHistory(messages: AgentMessage[]): boolean {
+	let changed = false;
+	const repairString = (value: string): string => {
+		const next = neutralizeReservedControlTokens(value);
+		if (next !== value) changed = true;
+		return next;
+	};
+	for (const message of messages) {
+		const content = (message as { content?: unknown }).content;
+		if (typeof content === "string") {
+			(message as { content: string }).content = repairString(content);
+		} else if (Array.isArray(content)) {
+			for (const block of content) {
+				if (!block || typeof block !== "object") continue;
+				const record = block as Record<string, unknown>;
+				for (const key of ["text", "thinking"]) {
+					const value = record[key];
+					if (typeof value === "string") record[key] = repairString(value);
+				}
+			}
+		}
+	}
+	return changed;
+}
+
+function managedFailureOutcome(message: AssistantMessage): ManagedAttemptOutcome {
+	return {
+		type: "retryable_discarded",
+		failure: { message, transportFailure: managedTransportFailure(message) },
+	};
+}
+
+function managedContextOverflowOutcome(message: AssistantMessage): ManagedAttemptOutcome {
+	return { type: "context_overflow_discarded", message };
+}
+
+function managedFailureMessage(error: unknown, config: AgentLoopConfig): AssistantMessage {
+	const errorMessage = managedProperty(error, "message");
+	const transportFailure = managedTransportFailure(error);
+	let fallbackMessage = "Managed fallback attempt failed";
+	if (typeof errorMessage === "string") fallbackMessage = errorMessage;
+	else {
+		try {
+			fallbackMessage = String(error);
+		} catch {
+			// Keep the stable local message for hostile wrappers.
+		}
+	}
+	return {
+		role: "assistant",
+		content: [],
+		api: config.model.api,
+		provider: config.model.provider,
+		model: config.model.id,
+		usage: {
+			input: 0,
+			output: 0,
+			cacheRead: 0,
+			cacheWrite: 0,
+			totalTokens: 0,
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+		},
+		stopReason: "error",
+		errorMessage: fallbackMessage,
+		...(transportFailure ? { transportFailure } : {}),
+		timestamp: Date.now(),
+	};
 }
 
 class HarmonyLeakInterruption extends Error {
@@ -132,6 +278,7 @@ export function agentLoop(
 	config: AgentLoopConfig,
 	signal?: AbortSignal,
 	streamFn?: StreamFn,
+	emitManagedAgentStart = true,
 ): EventStream<AgentEvent, AgentMessage[]> {
 	const stream = createAgentStream();
 
@@ -141,16 +288,19 @@ export function agentLoop(
 			...context,
 			messages: [...context.messages, ...prompts],
 		};
-
-		stream.push({ type: "agent_start" });
-		stream.push({ type: "turn_start" });
+		const transaction = config.fallbackManaged
+			? new ManagedAttemptTransaction(stream, config.onAssistantMessageEvent, config.model)
+			: undefined;
+		const attemptStream = transaction ?? stream;
+		if (!config.fallbackManaged || emitManagedAgentStart) stream.push({ type: "agent_start" });
+		attemptStream.push({ type: "turn_start" });
 		for (const prompt of prompts) {
 			stream.push({ type: "message_start", message: prompt });
 			stream.push({ type: "message_end", message: prompt });
 		}
 
 		try {
-			await runLoop(currentContext, newMessages, config, signal, stream, streamFn);
+			await runLoop(currentContext, newMessages, config, signal, stream, streamFn, transaction);
 		} catch (err) {
 			stream.fail(err);
 		}
@@ -172,6 +322,7 @@ export function agentLoopContinue(
 	config: AgentLoopConfig,
 	signal?: AbortSignal,
 	streamFn?: StreamFn,
+	emitManagedAgentStart = true,
 ): EventStream<AgentEvent, AgentMessage[]> {
 	if (context.messages.length === 0) {
 		throw new Error("Cannot continue: no messages in context");
@@ -186,12 +337,15 @@ export function agentLoopContinue(
 	(async () => {
 		const newMessages: AgentMessage[] = [];
 		const currentContext: AgentContext = { ...context };
-
-		stream.push({ type: "agent_start" });
-		stream.push({ type: "turn_start" });
+		const transaction = config.fallbackManaged
+			? new ManagedAttemptTransaction(stream, config.onAssistantMessageEvent, config.model)
+			: undefined;
+		const attemptStream = transaction ?? stream;
+		if (!config.fallbackManaged || emitManagedAgentStart) stream.push({ type: "agent_start" });
+		attemptStream.push({ type: "turn_start" });
 
 		try {
-			await runLoop(currentContext, newMessages, config, signal, stream, streamFn);
+			await runLoop(currentContext, newMessages, config, signal, stream, streamFn, transaction);
 		} catch (err) {
 			stream.fail(err);
 		}
@@ -207,6 +361,475 @@ function createAgentStream(): EventStream<AgentEvent, AgentMessage[]> {
 	);
 }
 
+/**
+ * Hard work budget for one degraded snapshot: every visited node AND every
+ * enumerated own key is debited against this budget before it is processed
+ * (accessor keys and re-visits of shared objects included), and any remainder
+ * collapses to the deterministic `"[truncated]"` placeholder. Well above
+ * ordinary streamed events; it only bounds hostile graphs.
+ */
+export const MANAGED_SNAPSHOT_MAX_NODES = 100_000;
+
+/**
+ * Cycle-aware deep clone that always returns a detached, JSON-serializable
+ * value. Used whenever a detached snapshot cannot be safely obtained or
+ * measured: after `structuredClone` fails, and again when a (successfully
+ * cloned) snapshot cannot be serialized for byte accounting.
+ *
+ * Totality rules — the walk must never dispatch through payload-controlled
+ * code, throw, or do unbounded work:
+ * - proxies (revoked or live) are collapsed to `"[unserializable]"` BEFORE
+ *   any reflective operation, so `ownKeys`/descriptor traps are never
+ *   dispatched (`util.types.isProxy` identifies proxies without touching
+ *   their handlers);
+ * - only intrinsics are used on the remaining ordinary objects (no
+ *   `input.map`, no `input.getTime()`, no `input.length` reads);
+ * - arrays are enumerated through their own present keys, never their
+ *   declared length, so a sparse array cannot force a dense allocation
+ *   proportional to `length`; sparse/exotic arrays degrade to a null-proto
+ *   record of their present indices, and the dense-shape decision verifies
+ *   every index against its ordinal;
+ * - the walk debits `maxNodes` budget per visited node and per enumerated
+ *   key before processing it; anything beyond the budget becomes
+ *   `"[truncated]"` (the one linear primitive per visited node is a single
+ *   `Object.keys` call on a non-proxy object the process already holds);
+ * - property values are read via own-property descriptors, so accessors are
+ *   never invoked (a snapshot must not cause observable side effects) and are
+ *   replaced with `"[accessor]"`;
+ * - functions/symbols and any property that cannot be read safely become
+ *   short placeholders, `bigint` becomes its decimal string, and references
+ *   back into the current path collapse to `"[Circular]"`;
+ * - records are built on a null prototype so a `__proto__` key cannot mutate
+ *   the clone's prototype chain.
+ *
+ * Exported for direct regression coverage of the budget accounting; runtime
+ * callers use the default budget via {@link managedAttemptSnapshot}.
+ */
+export function sanitizedDetachedClone<T>(value: T, maxNodes: number = MANAGED_SNAPSHOT_MAX_NODES): T {
+	const path = new Set<object>();
+	let budget = maxNodes;
+	const takeBudget = (units: number): boolean => {
+		if (budget < units) {
+			budget = 0;
+			return false;
+		}
+		budget -= units;
+		return true;
+	};
+	const walk = (input: unknown): unknown => {
+		if (!takeBudget(1)) return "[truncated]";
+		if (typeof input === "bigint") return String(input);
+		if (typeof input === "function" || typeof input === "symbol") return "[unserializable]";
+		if (input === null || typeof input !== "object") return input;
+		if (nodeUtilTypes.isProxy(input)) return "[unserializable]";
+		if (path.has(input)) return "[Circular]";
+		path.add(input);
+		const readOwnValue = (key: string): unknown => {
+			try {
+				const descriptor = Object.getOwnPropertyDescriptor(input, key);
+				return descriptor === undefined
+					? "[unserializable]"
+					: "value" in descriptor
+						? walk(descriptor.value)
+						: "[accessor]";
+			} catch {
+				return "[unserializable]";
+			}
+		};
+		try {
+			if (Array.isArray(input)) {
+				// Own present keys only: iterating the declared length would
+				// densify holes, and `Object.keys` is proportional to the
+				// elements that actually exist.
+				const keys = Object.keys(input);
+				if (!takeBudget(keys.length)) return "[truncated]";
+				const indexKeys: string[] = [];
+				let hasExtraProps = false;
+				for (const key of keys) {
+					const index = Number(key);
+					if (String(index) === key && index >= 0) indexKeys.push(key);
+					else hasExtraProps = true;
+				}
+				let dense = !hasExtraProps;
+				if (dense) {
+					for (let ordinal = 0; ordinal < indexKeys.length; ordinal++) {
+						if (Number(indexKeys[ordinal]) !== ordinal) {
+							dense = false;
+							break;
+						}
+					}
+				}
+				if (dense) {
+					const out: unknown[] = [];
+					for (const key of indexKeys) out.push(readOwnValue(key));
+					return out;
+				}
+				const sparse: Record<string, unknown> = Object.create(null);
+				for (const key of indexKeys) sparse[key] = readOwnValue(key);
+				return sparse;
+			}
+			let dateTime: number | undefined;
+			try {
+				// `isDate` checks the [[DateValue]] internal slot without walking
+				// the prototype chain — `instanceof Date` would dispatch a proxy
+				// prototype's getPrototypeOf trap and do unbudgeted linear work
+				// on deep ordinary chains.
+				dateTime = nodeUtilTypes.isDate(input) ? Date.prototype.getTime.call(input) : undefined;
+			} catch {
+				dateTime = undefined;
+			}
+			if (dateTime !== undefined) return new Date(dateTime);
+			const keys = Object.keys(input);
+			if (!takeBudget(keys.length)) return "[truncated]";
+			const record: Record<string, unknown> = Object.create(null);
+			for (const key of keys) record[key] = readOwnValue(key);
+			return record;
+		} catch {
+			// Brand checks / key enumeration on exotic objects can throw;
+			// collapse only this node, not its ancestors.
+			return "[unserializable]";
+		} finally {
+			path.delete(input);
+		}
+	};
+	return walk(value) as T;
+}
+
+/**
+ * Capture an event-time value because providers commonly mutate partial
+ * messages in place. The snapshot MUST always be detached from the caller's
+ * object graph — replaying a live reference would surface the final mutation
+ * instead of the event-time value. It must also never throw: staged payloads
+ * can carry non-cloneable objects during provisional assistant streaming
+ * (e.g. a live `Headers` inside a provider error's `transportFailure` from a
+ * legacy payload), and a thrown `DataCloneError` here would mask the real
+ * provider outcome and burn the whole fallback chain.
+ */
+function managedAttemptSnapshotDetailed<T>(value: T): { snapshot: T; degraded: boolean } {
+	try {
+		return { snapshot: structuredClone(value), degraded: false };
+	} catch {
+		return { snapshot: sanitizedDetachedClone(value), degraded: true };
+	}
+}
+
+function managedAttemptSnapshot<T>(value: T): T {
+	return managedAttemptSnapshotDetailed(value).snapshot;
+}
+
+/**
+ * Recover the required assistant-message shell when a managed snapshot degrades
+ * at its root (notably for Proxy-wrapped provider messages). Only known fields
+ * are read, and executable content is retained only when it has its complete
+ * discriminant shape.
+ */
+function managedAssistantShell(value: unknown, model: AgentLoopConfig["model"]): AssistantMessage {
+	const detailed = managedAttemptSnapshotDetailed(value);
+	const source = isManagedPlainRecord(detailed.snapshot) ? detailed.snapshot : value;
+	if (managedProperty(source, "role") !== "assistant") throw new ManagedAttemptSnapshotError();
+	const rawContent = managedAttemptSnapshot(managedProperty(source, "content"));
+	if (!Array.isArray(rawContent)) throw new ManagedAttemptSnapshotError();
+	const content = rawContent.flatMap(block => {
+		const normalized = managedAssistantContent(block);
+		return normalized ? [normalized] : [];
+	});
+	const usage = managedAssistantUsage(managedAttemptSnapshot(managedProperty(source, "usage")));
+	const api = managedProperty(source, "api");
+	const provider = managedProperty(source, "provider");
+	const messageModel = managedProperty(source, "model");
+	const stopReasonValue = managedProperty(source, "stopReason");
+	const stopReason =
+		stopReasonValue === "stop" ||
+		stopReasonValue === "length" ||
+		stopReasonValue === "toolUse" ||
+		stopReasonValue === "error" ||
+		stopReasonValue === "aborted"
+			? stopReasonValue
+			: "stop";
+	const timestamp = managedProperty(source, "timestamp");
+	const transportFailure = managedTransportFailure(value);
+	const errorMessage = managedProperty(source, "errorMessage");
+	const errorStatus = managedProperty(source, "errorStatus");
+	const safeMetadata: Record<string, unknown> = isManagedPlainRecord(detailed.snapshot)
+		? { ...detailed.snapshot }
+		: {};
+	delete safeMetadata.errorMessage;
+	delete safeMetadata.errorStatus;
+	delete safeMetadata.transportFailure;
+	return {
+		...safeMetadata,
+		role: "assistant",
+		content,
+		api: typeof api === "string" ? (api as AssistantMessage["api"]) : model.api,
+		provider: typeof provider === "string" ? (provider as AssistantMessage["provider"]) : model.provider,
+		model: typeof messageModel === "string" ? messageModel : model.id,
+		usage,
+		stopReason,
+		timestamp: typeof timestamp === "number" && Number.isFinite(timestamp) ? timestamp : Date.now(),
+		...(transportFailure ? { transportFailure } : {}),
+		...(typeof errorMessage === "string" ? { errorMessage } : {}),
+		...(typeof errorStatus === "number" && Number.isFinite(errorStatus) ? { errorStatus } : {}),
+	};
+}
+
+function managedAssistantContent(value: unknown): AssistantMessage["content"][number] | undefined {
+	if (!isManagedPlainRecord(value)) return undefined;
+	const type = managedProperty(value, "type");
+	if (type === "text") {
+		const text = managedProperty(value, "text");
+		return typeof text === "string" ? { type, text } : undefined;
+	}
+	if (type === "thinking") {
+		const thinking = managedProperty(value, "thinking");
+		return typeof thinking === "string" ? { type, thinking } : undefined;
+	}
+	if (type === "redactedThinking") {
+		const data = managedProperty(value, "data");
+		return typeof data === "string" ? { type, data } : undefined;
+	}
+	if (type !== "toolCall") return undefined;
+	const id = managedProperty(value, "id");
+	const name = managedProperty(value, "name");
+	const argumentsValue = managedProperty(value, "arguments");
+	if (typeof id !== "string" || typeof name !== "string" || !isManagedPlainRecord(argumentsValue)) return undefined;
+	const thoughtSignature = managedProperty(value, "thoughtSignature");
+	const intent = managedProperty(value, "intent");
+	const customWireName = managedProperty(value, "customWireName");
+	const incompleteArguments = managedProperty(value, "incompleteArguments");
+	return {
+		type,
+		id,
+		name,
+		arguments: argumentsValue,
+		...(typeof thoughtSignature === "string" ? { thoughtSignature } : {}),
+		...(typeof intent === "string" ? { intent } : {}),
+		...(typeof customWireName === "string" ? { customWireName } : {}),
+		...(typeof incompleteArguments === "boolean" ? { incompleteArguments } : {}),
+	};
+}
+
+function managedAssistantUsage(value: unknown): AssistantMessage["usage"] {
+	const number = (key: string): number => {
+		const candidate = managedProperty(value, key);
+		return typeof candidate === "number" && Number.isFinite(candidate) ? candidate : 0;
+	};
+	const costValue = managedProperty(value, "cost");
+	const costNumber = (key: string): number => {
+		const candidate = managedProperty(costValue, key);
+		return typeof candidate === "number" && Number.isFinite(candidate) ? candidate : 0;
+	};
+	return {
+		input: number("input"),
+		output: number("output"),
+		cacheRead: number("cacheRead"),
+		cacheWrite: number("cacheWrite"),
+		totalTokens: number("totalTokens"),
+		cost: {
+			input: costNumber("input"),
+			output: costNumber("output"),
+			cacheRead: costNumber("cacheRead"),
+			cacheWrite: costNumber("cacheWrite"),
+			total: costNumber("total"),
+		},
+	};
+}
+
+function managedAssistantEventSnapshot(event: AssistantMessageEvent, message: AssistantMessage): AssistantMessageEvent {
+	const snapshot = managedAttemptSnapshot(event);
+	if (!isManagedPlainRecord(snapshot)) throw new ManagedAttemptSnapshotError();
+	const type = managedProperty(snapshot, "type");
+	const contentIndex = managedProperty(snapshot, "contentIndex");
+	const indexed = () => {
+		if (!Number.isInteger(contentIndex) || (contentIndex as number) < 0) throw new ManagedAttemptSnapshotError();
+		return contentIndex as number;
+	};
+	if (type === "start") return { type, partial: message };
+	if (type === "text_start" || type === "thinking_start" || type === "toolcall_start")
+		return { type, contentIndex: indexed(), partial: message };
+	if (type === "text_delta" || type === "thinking_delta" || type === "toolcall_delta") {
+		const delta = managedProperty(snapshot, "delta");
+		if (typeof delta !== "string") throw new ManagedAttemptSnapshotError();
+		return { type, contentIndex: indexed(), delta, partial: message };
+	}
+	if (type === "text_end" || type === "thinking_end") {
+		const content = managedProperty(snapshot, "content");
+		if (typeof content !== "string") throw new ManagedAttemptSnapshotError();
+		return { type, contentIndex: indexed(), content, partial: message };
+	}
+	if (type === "toolcall_end") {
+		const toolCall = managedAssistantContent(managedProperty(snapshot, "toolCall"));
+		if (toolCall?.type !== "toolCall") throw new ManagedAttemptSnapshotError();
+		return { type, contentIndex: indexed(), toolCall, partial: message };
+	}
+	if (type === "done") {
+		const reason = managedProperty(snapshot, "reason");
+		if (reason !== "stop" && reason !== "length" && reason !== "toolUse") throw new ManagedAttemptSnapshotError();
+		return { type, reason, message };
+	}
+	if (type === "error") {
+		const reason = managedProperty(snapshot, "reason");
+		if (reason !== "aborted" && reason !== "error") throw new ManagedAttemptSnapshotError();
+		return { type, reason, error: message };
+	}
+	throw new ManagedAttemptSnapshotError();
+}
+
+function isManagedPlainRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value) && !nodeUtilTypes.isProxy(value);
+}
+
+/**
+ * Holds managed-attempt assistant output above the public event stream. A
+ * cancelled provider attempt is therefore unobservable to sessions and their
+ * side-effect consumers. Non-managed streams bypass this object entirely.
+ */
+class ManagedAttemptTransaction {
+	#batch: Array<
+		| { type: "event"; event: AgentEvent }
+		| { type: "assistant_event"; message: AssistantMessage; event: AssistantMessageEvent }
+	> = [];
+	#stagedEventCount = 0;
+	#stagedBytes = 0;
+	#discarded = false;
+	#committed = false;
+
+	constructor(
+		private readonly stream: EventStream<AgentEvent, AgentMessage[]>,
+		private readonly onAssistantMessageEvent:
+			| ((message: AssistantMessage, event: AssistantMessageEvent) => void)
+			| undefined,
+		private readonly model: AgentLoopConfig["model"],
+	) {}
+
+	push(event: AgentEvent): void {
+		if (this.#committed) {
+			this.stream.push(event);
+			return;
+		}
+		this.#stage(event);
+	}
+
+	end(messages: AgentMessage[]): void {
+		this.stream.end(messages);
+	}
+
+	stageAssistantMessageEvent(message: AssistantMessage, event: AssistantMessageEvent): void {
+		const partial = managedAssistantShell(message, this.model);
+		this.#batch.push({
+			type: "assistant_event",
+			message: partial,
+			event: managedAssistantEventSnapshot(event, partial),
+		});
+	}
+
+	flush(): void {
+		if (this.#discarded || this.#committed) return;
+		for (const item of this.#batch) {
+			if (item.type === "assistant_event") {
+				this.onAssistantMessageEvent?.(item.message, item.event);
+			} else {
+				this.stream.push(item.event);
+			}
+		}
+		this.#batch = [];
+		this.#stagedBytes = 0;
+		this.#stagedEventCount = 0;
+		this.#committed = true;
+	}
+
+	discard(): void {
+		this.#batch = [];
+		this.#stagedBytes = 0;
+		this.#stagedEventCount = 0;
+		this.#discarded = true;
+	}
+
+	#wouldOverflow(bytes: number): boolean {
+		return (
+			this.#stagedEventCount + 1 > MANAGED_ATTEMPT_MAX_STAGED_EVENTS ||
+			this.#stagedBytes + bytes > MANAGED_ATTEMPT_MAX_STAGED_BYTES
+		);
+	}
+
+	#stage(event: AgentEvent): void {
+		// Measure the raw event FIRST so an oversized payload is rejected
+		// before the snapshot duplicates it — the staged-byte cap exists to
+		// bound memory, so cloning ahead of the check would defeat it.
+		// Cyclic/JSON-hostile events cannot be pre-measured; only those fall
+		// through to snapshot-then-measure, where the sanitized detached form
+		// is the cycle-safe estimator.
+		let bytes: number | undefined;
+		try {
+			bytes = managedAttemptTextEncoder.encode(JSON.stringify(event)).byteLength;
+		} catch {
+			bytes = undefined;
+		}
+		if (bytes !== undefined && this.#wouldOverflow(bytes)) {
+			this.discard();
+			throw new ManagedAttemptBufferOverflowError();
+		}
+		const detailed = managedAttemptSnapshotDetailed(this.#repairAssistantEvent(event));
+		let snapshot = detailed.snapshot;
+		if (bytes === undefined || detailed.degraded) {
+			// Account the bytes of what is actually retained: a degraded
+			// snapshot replaces non-JSON leaves with placeholders, so the raw
+			// pre-measure (which omits e.g. function-valued properties) can
+			// undercount the staged form.
+			try {
+				bytes = managedAttemptTextEncoder.encode(JSON.stringify(snapshot)).byteLength;
+			} catch {
+				try {
+					snapshot = sanitizedDetachedClone(snapshot);
+					bytes = managedAttemptTextEncoder.encode(JSON.stringify(snapshot)).byteLength;
+				} catch {
+					bytes = undefined;
+				}
+			}
+			if (bytes === undefined) {
+				// The sanitizer's output is total (detached, JSON-safe), so this
+				// is unreachable unless the sanitizer itself regresses. Fail as a
+				// dedicated local error: it carries no transport facts, so it is
+				// non-retryable and can never be misattributed to the provider.
+				this.discard();
+				throw new ManagedAttemptSnapshotError();
+			}
+			if (this.#wouldOverflow(bytes)) {
+				this.discard();
+				throw new ManagedAttemptBufferOverflowError();
+			}
+		}
+		this.#batch.push({ type: "event", event: snapshot });
+		this.#stagedEventCount += 1;
+
+		this.#stagedBytes += bytes;
+	}
+
+	#repairAssistantEvent(event: AgentEvent): AgentEvent {
+		if (event.type === "message_start" || event.type === "message_end" || event.type === "turn_end") {
+			return event.message.role === "assistant"
+				? { ...event, message: managedAssistantShell(event.message, this.model) }
+				: event;
+		}
+		if (event.type === "message_update") {
+			const message = managedAssistantShell(event.message, this.model);
+			return {
+				...event,
+				message,
+				assistantMessageEvent: managedAssistantEventSnapshot(event.assistantMessageEvent, message),
+			};
+		}
+		if (event.type === "agent_end") {
+			return {
+				...event,
+				messages: event.messages.map(message =>
+					message.role === "assistant" ? managedAssistantShell(message, this.model) : message,
+				),
+			};
+		}
+		return event;
+	}
+}
+
 /**
  * Build the `agent_end` event payload. When telemetry is enabled, snapshots
  * the run collector so consumers receive {@link AgentRunSummary} +
@@ -549,7 +1172,10 @@ async function runLoop(
 	signal: AbortSignal | undefined,
 	stream: EventStream<AgentEvent, AgentMessage[]>,
 	streamFn?: StreamFn,
+	initialTransaction?: ManagedAttemptTransaction,
 ): Promise<void> {
+	const loopSignal = signal ?? new AbortController().signal;
+
 	const telemetry = resolveTelemetry(config.telemetry, config.sessionId);
 	const invokeAgentSpan = startInvokeAgentSpan(telemetry, config.model);
 	const stepCounter = { count: 0 };
@@ -560,12 +1186,14 @@ async function runLoop(
 				currentContext,
 				newMessages,
 				config,
-				signal,
+				loopSignal,
+
 				stream,
 				telemetry,
 				invokeAgentSpan,
 				stepCounter,
 				streamFn,
+				initialTransaction,
 			),
 		);
 	} catch (err) {
@@ -587,18 +1215,28 @@ async function runLoopBody(
 	currentContext: AgentContext,
 	newMessages: AgentMessage[],
 	config: AgentLoopConfig,
-	signal: AbortSignal | undefined,
+	loopSignal: AbortSignal,
+
 	stream: EventStream<AgentEvent, AgentMessage[]>,
 	telemetry: AgentTelemetry | undefined,
 	invokeAgentSpan: Span | undefined,
 	stepCounter: StepCounter,
 	streamFn?: StreamFn,
+	initialTransaction?: ManagedAttemptTransaction,
 ): Promise<void> {
 	let firstTurn = true;
 	// Check for steering messages at start (user may have typed while waiting)
 	let pendingMessages: AgentMessage[] = (await config.getSteeringMessages?.()) || [];
 	let harmonyRetryAttempt = 0;
+	// Whether at least one assistant response has been produced in THIS run. The
+	// mid-run maintenance checkpoint only fires between tool iterations (after a
+	// model response); pre-turn maintenance is the pre-prompt check's job, so the
+	// first iteration is skipped to avoid duplicating/racing it.
+	let modelHasResponded = false;
 	let harmonyTruncateResumeCount = 0;
+	// Fires at most one repaired resend per run for the poisoned-history
+	// `invalid_prompt` circuit breaker below.
+	let invalidPromptRepairAttempted = false;
 
 	// Outer loop: continues when queued follow-up messages arrive after agent would stop
 	while (true) {
@@ -606,13 +1244,21 @@ async function runLoopBody(
 
 		// Inner loop: process tool calls and steering messages
 		while (hasMoreToolCalls || pendingMessages.length > 0) {
+			const transaction =
+				initialTransaction ??
+				(config.fallbackManaged
+					? new ManagedAttemptTransaction(stream, config.onAssistantMessageEvent, config.model)
+					: undefined);
+			initialTransaction = undefined;
+			const attemptStream = transaction ?? stream;
 			if (!firstTurn) {
-				stream.push({ type: "turn_start" });
+				attemptStream.push({ type: "turn_start" });
 			} else {
 				firstTurn = false;
 			}
 
-			// Process pending messages (inject before next assistant response)
+			// Commit queued user input outside the provisional assistant transaction so a
+			// discarded managed attempt cannot lose it before its retry continuation.
 			if (pendingMessages.length > 0) {
 				for (const message of pendingMessages) {
 					stream.push({ type: "message_start", message });
@@ -623,20 +1269,63 @@ async function runLoopBody(
 				pendingMessages = [];
 			}
 
+			// Cooperative mid-run context maintenance. Runs after pending
+			// tool/steering messages are materialized into durable context and
+			// before syncContextBeforeModelCall / the model call — the only
+			// boundary where the full unsent context is already durable. A
+			// non-"not-needed" outcome means context was (or was attempted to be)
+			// rewritten, so end the run WITHOUT the lossy agent_end finalization;
+			// the maintenance owner resumes the run on the rewritten context.
+			// "not-needed" falls through to the model call.
+			if (config.maintainContext && modelHasResponded && !loopSignal.aborted) {
+				const lifecycle = {
+					signal: loopSignal,
+					awaitEventDrain: (invocationSignal: AbortSignal) =>
+						stream.waitForConsumerDrain(AbortSignal.any([loopSignal, invocationSignal])),
+				};
+				const maintenanceOutcome = await config.maintainContext(currentContext, lifecycle);
+				// A callback can settle after its loop has been cancelled. Never let a
+				// stale "not-needed" fall through to streamAssistantResponse, which
+				// invokes the provider before it observes the aborted signal.
+				const outcome = loopSignal.aborted ? "aborted" : maintenanceOutcome;
+
+				if (outcome !== "not-needed") {
+					stream.push({
+						type: "agent_end",
+						messages: newMessages,
+						stopReason: "maintenance",
+						maintenanceOutcome: outcome,
+					});
+					stream.end(newMessages);
+					return;
+				}
+			}
+
 			// Refresh prompt/tool context from live state before each model call
 			if (config.syncContextBeforeModelCall) {
 				await config.syncContextBeforeModelCall(currentContext);
 			}
 
+			const contextMessageCount = currentContext.messages.length;
+			const newMessageCount = newMessages.length;
+
 			// Stream assistant response
 			let recovered: HarmonyRecoveredToolCall | undefined;
 			let message: AssistantMessage;
+			const attemptTransaction = transaction;
 			try {
+				const attemptConfig = attemptTransaction
+					? {
+							...config,
+							onAssistantMessageEvent: (partial: AssistantMessage, event: AssistantMessageEvent) =>
+								attemptTransaction.stageAssistantMessageEvent(partial, event),
+						}
+					: config;
 				message = await streamAssistantResponse(
 					currentContext,
-					config,
-					signal,
-					stream,
+					attemptConfig,
+					loopSignal,
+					attemptTransaction ? (attemptTransaction as unknown as EventStream<AgentEvent, AgentMessage[]>) : stream,
 					telemetry,
 					invokeAgentSpan,
 					stepCounter,
@@ -652,7 +1341,30 @@ async function runLoopBody(
 				harmonyRetryAttempt = 0;
 				harmonyTruncateResumeCount = 0;
 			} catch (err) {
-				if (!(err instanceof HarmonyLeakInterruption)) throw err;
+				if (!(err instanceof HarmonyLeakInterruption)) {
+					const failureMessage = managedFailureMessage(err, config);
+					if (config.fallbackManaged && transaction && managedContextOverflow(failureMessage, config)) {
+						transaction.discard();
+						currentContext.messages.splice(contextMessageCount);
+						newMessages.splice(newMessageCount);
+						await config.onManagedAttemptOutcome?.(managedContextOverflowOutcome(failureMessage));
+						stream.end(newMessages);
+						return;
+					}
+					if (config.fallbackManaged && transaction && managedRetryableFailure(err)) {
+						transaction.discard();
+						currentContext.messages.splice(contextMessageCount);
+						newMessages.splice(newMessageCount);
+						await config.onManagedAttemptOutcome?.(managedFailureOutcome(failureMessage));
+						stream.end(newMessages);
+						return;
+					}
+					throw err;
+				}
+				if (config.fallbackManaged) {
+					await emitHarmonyAudit(config, err, "escalated", harmonyRetryAttempt);
+					throw err;
+				}
 				if (err.recovered) {
 					if (harmonyTruncateResumeCount >= 2) {
 						await emitHarmonyAudit(config, err, "escalated", harmonyRetryAttempt);
@@ -694,22 +1406,84 @@ async function runLoopBody(
 					continue;
 				}
 			}
+			// Session-level invalid_prompt circuit breaker (bounded, neutralize-only).
+			// A poisoned-history rejection (`Request blocked (code=invalid_prompt)`) is
+			// a deterministic content fault: re-sending the same history re-triggers it,
+			// so naive session auto-retry would burn its whole budget re-poisoning the
+			// model. On the first invalid_prompt of this run, neutralize leaked control
+			// tokens in history IN PLACE (never dropping items). If that changed the
+			// outgoing bytes, resend exactly once with the repaired history; if
+			// neutralization cannot change anything (nothing left to repair), fall
+			// through to terminal handling and fail fast. Budget = one repaired resend.
+			// Runs before the response is committed so the resend is a clean retry;
+			// managed fallback owns its own retry policy, so this is scoped to the
+			// non-managed session path where uncontrolled auto-retry would recur.
+			if (
+				!config.fallbackManaged &&
+				message.stopReason === "error" &&
+				!invalidPromptRepairAttempted &&
+				isInvalidPromptError(message)
+			) {
+				invalidPromptRepairAttempted = true;
+				if (repairInvalidPromptHistory(currentContext.messages)) {
+					continue;
+				}
+			}
+
+			const overflow = managedContextOverflow(message, config);
+			if (config.fallbackManaged && overflow) {
+				transaction?.discard();
+				currentContext.messages.splice(contextMessageCount);
+				newMessages.splice(newMessageCount);
+				await config.onManagedAttemptOutcome?.(managedContextOverflowOutcome(message));
+				stream.end(newMessages);
+				return;
+			}
+
 			newMessages.push(message);
+			modelHasResponded = true;
 			let steeringMessagesFromExecution: AgentMessage[] | undefined;
 
-			// Detect empty "successful" responses (stopReason "stop" + empty content).
-			// Some proxies (e.g. LiteLLM) return this when the upstream model's context
-			// window is exceeded, fabricating a near-zero usage instead of surfacing an
-			// error. Without this guard the agent loop treats the empty response as a
-			// natural turn completion and stops, leaving the user with a frozen session.
-			// Promote it to an error so the overflow/compaction recovery path can fire.
-			if (message.stopReason === "stop" && message.content.length === 0 && isEmptyResponseOverflow(message)) {
+			// Preserve the historical public error conversion for unmanaged proxy overflows.
+			if (!config.fallbackManaged && message.stopReason === "stop" && message.content.length === 0 && overflow) {
 				message.stopReason = "error";
 				message.errorMessage = message.errorMessage
 					? `${message.errorMessage} | Provider returned an empty response with anomalously low token usage (possible context overflow via proxy)`
 					: "Provider returned an empty response with anomalously low token usage (possible context overflow via proxy)";
 			}
 
+			if (config.fallbackManaged && message.stopReason === "error" && managedRetryableFailure(message)) {
+				transaction?.discard();
+				currentContext.messages.splice(contextMessageCount);
+				newMessages.splice(newMessageCount);
+				await config.onManagedAttemptOutcome?.(managedFailureOutcome(message));
+				stream.end(newMessages);
+				return;
+			}
+
+			if (config.fallbackManaged && message.stopReason === "aborted") {
+				transaction?.discard();
+				currentContext.messages.splice(contextMessageCount);
+				newMessages.splice(newMessageCount);
+				await config.onManagedAttemptOutcome?.({ type: "run_terminal", reason: "cancelled" });
+				stream.end(newMessages);
+				return;
+			}
+			if (attemptTransaction) {
+				message = managedAssistantShell(message, config.model);
+				const index = currentContext.messages.length - 1;
+				if (index >= 0 && currentContext.messages[index]?.role === "assistant") {
+					currentContext.messages[index] = message;
+				}
+				newMessages[newMessages.length - 1] = message;
+			}
+
+			// One provider invocation is committed before any tool can run.
+			transaction?.flush();
+			if (config.fallbackManaged && message.stopReason !== "error" && message.stopReason !== "aborted") {
+				await config.onManagedAttemptAccepted?.();
+			}
+
 			if (message.stopReason === "error" || message.stopReason === "aborted") {
 				// Create placeholder tool results for any tool calls in the aborted message
 				// This maintains the tool_use/tool_result pairing that the API requires
@@ -747,7 +1521,7 @@ async function runLoopBody(
 				const executionResult = await executeToolCalls(
 					currentContext,
 					message,
-					signal,
+					loopSignal,
 					stream,
 					config,
 					telemetry,
@@ -925,8 +1699,10 @@ async function streamAssistantResponse(
 
 	try {
 		return await runInActiveSpan(chatSpan, async () => {
+			const fallbackAttempt = config.fallbackManaged ? config.nextFallbackAttempt?.(config.model) : undefined;
 			const response = await streamFunction(config.model, llmContext, {
 				...config,
+				fallbackAttempt,
 				apiKey: resolvedApiKey,
 				authCredentialType,
 				metadata: resolvedMetadata,
@@ -987,7 +1763,9 @@ async function streamAssistantResponse(
 
 					switch (event.type) {
 						case "start":
-							partialMessage = event.partial;
+							partialMessage = config.fallbackManaged
+								? managedAssistantShell(event.partial, config.model)
+								: event.partial;
 							context.messages.push(partialMessage);
 							addedPartial = true;
 							stream.push({ type: "message_start", message: { ...partialMessage } });
@@ -1003,19 +1781,23 @@ async function streamAssistantResponse(
 						case "thinking_start":
 						case "thinking_delta":
 						case "thinking_end":
+						case "reasoning_summary_start":
+						case "reasoning_summary_delta":
+						case "reasoning_summary_end":
 						case "toolcall_start":
 						case "toolcall_delta":
 						case "toolcall_end":
 							if (partialMessage) {
-								partialMessage = event.partial;
+								partialMessage = config.fallbackManaged
+									? managedAssistantShell(event.partial, config.model)
+									: event.partial;
+								const partialEvent = config.fallbackManaged ? { ...event, partial: partialMessage } : event;
 								context.messages[context.messages.length - 1] = partialMessage;
-								config.onAssistantMessageEvent?.(partialMessage, event);
-								if (signal?.aborted) {
-									continue;
-								}
+								config.onAssistantMessageEvent?.(partialMessage, partialEvent);
+								if (signal?.aborted) continue;
 								stream.push({
 									type: "message_update",
-									assistantMessageEvent: event,
+									assistantMessageEvent: partialEvent,
 									message: { ...partialMessage },
 								});
 							}
@@ -1023,7 +1805,9 @@ async function streamAssistantResponse(
 
 						case "done":
 						case "error": {
-							const finalMessage = await response.result();
+							const finalMessage = config.fallbackManaged
+								? managedAssistantShell(await response.result(), config.model)
+								: await response.result();
 							if (addedPartial) {
 								context.messages[context.messages.length - 1] = finalMessage;
 							} else {
@@ -1042,7 +1826,9 @@ async function streamAssistantResponse(
 				detachAbortListener?.();
 			}
 
-			const trailing = await response.result();
+			const trailing = config.fallbackManaged
+				? managedAssistantShell(await response.result(), config.model)
+				: await response.result();
 			await finishChat(trailing);
 			return trailing;
 		});