@namzu/sdk 51.1.0 → 52.1.0

package/src/runtime/query/iteration/index.ts

@@ -4,7 +4,10 @@ import {
 	extractFromUserMessage,
 } from '../../../compaction/extractor.js'
 import { estimateMessageTokens } from '../../../compaction/token-estimate.js'
-import { AUTO_CONTINUATION_USER_MESSAGE } from '../../../constants/continuation.js'
+import {
+	AUTO_CONTINUATION_USER_MESSAGE,
+	REASONING_CUT_USER_MESSAGE,
+} from '../../../constants/continuation.js'
 import { CHARS_PER_TOKEN } from '../../../constants/limits.js'
 import {
 	DEFAULT_STRUCTURED_OUTPUT_RETRIES,
@@ -12,7 +15,7 @@ import {
 } from '../../../constants/tools/index.js'
 import { withStreamedMessageIdentity } from '../../../manager/session/streamed-message-identity.js'
 import { renderSkillsSection } from '../../../persona/assembler.js'
-import { resolveProviderCapabilities } from '../../../provider/capabilities.js'
+import { modelReadsImages, resolveProviderCapabilities } from '../../../provider/capabilities.js'
 import { collectChatCompletion } from '../../../provider/collect-chat-completion.js'
 import { renderToolSchema } from '../../../registry/tool/schema.js'
 import { formatCompletionNotification } from '../../../scheduler/completion-inbox.js'
@@ -27,7 +30,7 @@ import { STRUCTURED_OUTPUT_TOOL_NAME } from '../../../tools/builtins/structuredO
 import type { ToolManager } from '../../../toolsets/manager.js'
 import type { CostInfo, TokenUsage } from '../../../types/common/index.js'
 import { NamzuError } from '../../../types/errors/index.js'
-import type { MessageId } from '../../../types/ids/index.js'
+import type { MessageId, SessionId, TurnId } from '../../../types/ids/index.js'
 import {
 	type Message,
 	type UserMessage,
@@ -35,7 +38,7 @@ import {
 	createRuntimeContextMessage,
 	createSystemMessage,
 } from '../../../types/message/index.js'
-import { classifyProviderError } from '../../../types/provider/errors.js'
+import { classifyProviderError, readOutputOverflow } from '../../../types/provider/errors.js'
 import type { ChatCompletionResponse } from '../../../types/provider/index.js'
 import type { AnswerReview, AnswerReviewContext } from '../../../types/session/answer-review.js'
 import type {
@@ -51,6 +54,7 @@ import { stableDigest } from '../../../utils/hash.js'
 import { generateMessageId } from '../../../utils/id.js'
 import { parseStructuredResultJson } from '../../../utils/structured-result-json.js'
 import { createCallbackInference } from '../callback-inference.js'
+import { SandboxAcquisitionStopped } from '../deferred-sandbox.js'
 import { deliverDurableInbound } from '../durable-inbound.js'
 import type { ToolCallOutcome } from '../executor.js'
 import { projectObservationContext } from '../observation-context.js'
@@ -75,18 +79,29 @@ import {
 } from './outstanding-work.js'
 import { runAdvisoryPhase } from './phases/advisory.js'
 import { runIterationCheckpoint } from './phases/checkpoint.js'
+import { compactionBreaker } from './phases/compaction-breaker.js'
 import {
+	AUTOMATIC_COMPACTION_FAILED,
+	OVERFLOW_RELIEF_LIMIT,
 	activeContextWindow,
+	clearCompactionErrorNote,
+	compactionErrorNote,
 	measureContext,
 	relieveOverflow,
 	runCompactionCheck,
+	stopOnRefill,
 } from './phases/compaction.js'
 import { runHandoffPause } from './phases/handoff.js'
 import type { IterationContext } from './phases/index.js'
 import { runPlanGate } from './phases/plan.js'
 import { runToolReview } from './phases/tool-review.js'
 import { refreshWorkingMemory, splitWorkingMemoryForRequest } from './phases/working-memory.js'
-import { streamWithProviderRejectedImageRecovery } from './provider-rejected-image.js'
+import {
+	type TextOnlyModelRecovery,
+	type TextOnlyModelRefusal,
+	streamWithProviderRejectedImageRecovery,
+} from './provider-rejected-image.js'
+import { type MediaRemoval, RequestRepair } from './request-repair.js'
 import {
 	type StepShaping,
 	appendWorkContext,
@@ -125,6 +140,11 @@ export type { ToolReviewOutcome } from './phases/index.js'
  */
 const DEFAULT_ANSWER_REVIEW_LIMIT = 3
 
+/** Left unused when an output cap is shrunk to fit the window (reference: 1000). */
+const OUTPUT_CAP_MARGIN_TOKENS = 1000
+/** A shrunk output cap below this is not worth a call (reference floor: 3000). */
+const MIN_OUTPUT_CAP_TOKENS = 3000
+
 // Ending a turn changes the available actions, not the strength of its evidence.
 // Use the same standard for warning closure and empty-completion recovery.
 const CLOSING_RESPONSE_GUIDANCE =
@@ -132,6 +152,11 @@ const CLOSING_RESPONSE_GUIDANCE =
 
 export { awaitedJobGraceMs, settleGraceMs } from './outstanding-work.js'
 
+/** One provider's model, as {@link IterationOrchestrator} remembers it. */
+function textOnlyKey(providerId: string, model: string): string {
+	return `${providerId}\u0000${model}`
+}
+
 export class IterationOrchestrator {
 	private ctx: IterationContext
 	private advisoryTurn:
@@ -179,6 +204,73 @@ export class IterationOrchestrator {
 	}
 	/** Rich tool blocks already reported; durable history is scanned every turn. */
 	private readonly warnedRichToolResults = new Set<string>()
+	/** What this run has learned about requests its provider rejects as invalid, and how to repair them. */
+	private readonly requestRepair = new RequestRepair({
+		debug: (message) => this.ctx.log.debug(message),
+		onMediaRemoved: (removal) => this.noteMediaRemoved(removal),
+		servedBy: () => this.ctx.servingMember?.(),
+	})
+	/**
+	 * Provider and model pairs that refused a request for holding an image; they
+	 * get none for the rest of the run. Keyed by both: one model id can be served
+	 * by two members of a fallback chain, and only the one that refused is known.
+	 */
+	private readonly textOnlyModels = new Set<string>()
+
+	/**
+	 * The member a request for `model` goes to first. A fallback chain keeps
+	 * serving from the member it last moved to, so that member, not the head,
+	 * is the one whose reading of images counts.
+	 */
+	private servingModel(model: string): { readonly providerId: string; readonly model: string } {
+		const serving = this.ctx.servingMember?.()
+		return {
+			providerId: serving?.providerId ?? this.ctx.provider.id,
+			model: serving?.model ?? model,
+		}
+	}
+
+	/** Whether a request for `model` may carry images: the driver's catalogue and this run's own evidence agree. */
+	private modelReadsImages(model: string): boolean {
+		const serving = this.servingModel(model)
+		return (
+			!this.textOnlyModels.has(textOnlyKey(serving.providerId, serving.model)) &&
+			modelReadsImages(this.ctx.provider, model)
+		)
+	}
+
+	/** What a request for `model` does when its model turns out to read text only. */
+	private textOnlyRecovery(model: string): TextOnlyModelRecovery {
+		return {
+			servedBy: () => this.servingModel(model),
+			onAccepted: (refused) => this.noteTextOnlyModel(refused),
+		}
+	}
+
+	/**
+	 * A provider refused a request for holding an image its model cannot read, and
+	 * the retry without images was accepted. Stop sending images to it, and say so
+	 * once, so the host can remember the model beyond this run.
+	 */
+	private async noteTextOnlyModel(refused: TextOnlyModelRefusal): Promise<void> {
+		const key = textOnlyKey(refused.providerId, refused.model ?? '')
+		if (this.textOnlyModels.has(key)) return
+		this.textOnlyModels.add(key)
+		const { providerId, model } = refused
+		this.ctx.log.warn('Capability mismatch: the model cannot read images', {
+			[GENAI.SYSTEM]: providerId,
+			[GENAI.REQUEST_MODEL]: model ?? '',
+		})
+		await this.ctx.emitEvent?.({
+			type: 'capability_warning',
+			turnId: this.ctx.recorder.turnId,
+			capability: 'vision',
+			contentSource: 'history',
+			providerId,
+			...(model !== undefined ? { model } : {}),
+			message: `Model '${model ?? 'unknown'}' on provider '${providerId}' refused a request that held an image, so images are left out of its requests. They stay in the conversation and are sent again to a model that reads them.`,
+		})
+	}
 	/**
 	 * The previous iteration held a `stopWhen` decision open for a worker.
 	 *
@@ -194,6 +286,74 @@ export class IterationOrchestrator {
 	 * sets it.
 	 */
 	private stopDeferredForOutstandingWork = false
+	/** Nudges sent since the model last finished a call without hitting its output cap. */
+	private outputContinuations = 0
+	/**
+	 * `turn_end` (and, for a child, `subagent_stop`) fired when the model
+	 * finished and no hook asked for more. `finalizeTurn` then does not fire
+	 * them a second time.
+	 */
+	private turnEndFired = false
+	/** A hook already kept this turn going once: it is asked again with `stop_hook_active`. */
+	private stopHookActive = false
+	get turnEndHooksFired(): boolean {
+		return this.turnEndFired
+	}
+
+	/**
+	 * Fire `turn_end` (and `subagent_stop` for a child) at the point the model
+	 * has finished, and read the answer.
+	 *
+	 * A hook that answers `skip` is refusing to let the turn end: its reasons
+	 * are returned, joined, as feedback for the model. A hook that asks for the
+	 * turn to halt wins over any such feedback (`takeHalt`). With nothing asked,
+	 * the events have fired for this turn and the finalizer does not repeat them.
+	 */
+	private async *askStopHooks(): AsyncGenerator<SessionEvent, string | undefined> {
+		const manager = this.ctx.pluginManager
+		if (!manager) return undefined
+		const recorder = this.ctx.recorder
+		const feedback: string[] = []
+		const ask = async (
+			event: 'turn_end' | 'subagent_stop',
+			extra: { parentSessionId?: SessionId; parentTurnId?: TurnId },
+		): Promise<void> => {
+			const results = await manager.executeHooks(
+				event,
+				{
+					sessionId: recorder.sessionId,
+					turnId: recorder.turnId,
+					...extra,
+					...(this.stopHookActive ? { stopHookActive: true } : {}),
+					signal: this.ctx.abortController.signal,
+				},
+				this.ctx.emitEvent,
+			)
+			applyLifecycleHookResults(event, results)
+			for (const result of results) {
+				if (result.action === 'skip') feedback.push(result.reason)
+				if ((result.action === 'continue' || result.action === 'skip') && result.halt) {
+					this.ctx.toolExecutor.requestHalt?.(result.halt.reason)
+				}
+			}
+		}
+		await ask('turn_end', {})
+		yield* this.ctx.drainPending()
+		if (this.ctx.parentSessionId !== undefined) {
+			await ask('subagent_stop', {
+				parentSessionId: this.ctx.parentSessionId,
+				...(this.ctx.parentTurnId !== undefined ? { parentTurnId: this.ctx.parentTurnId } : {}),
+			})
+			yield* this.ctx.drainPending()
+		}
+		if (feedback.length === 0) {
+			this.turnEndFired = true
+			return undefined
+		}
+		this.stopHookActive = true
+		return feedback.join('\n')
+	}
+
 	/** One current input, independent of the compactable history array. */
 	private latestUserMessage: UserMessage | undefined
 	private initialDurableDelivered = false
@@ -365,16 +525,22 @@ export class IterationOrchestrator {
 		// checkpoint names the message the turn is answering.
 		await this.ctx.checkpointMgr.markLoopStart?.(recorder)
 
-		// One context-overflow relief per *stuck point*, not per turn.
+		// Context-overflow relief is a two-rung ladder per *stuck point*, not per
+		// turn, as in the reference terminal (at most two reactive compactions per
+		// overflow): the first relief, then one deeper pass if the retry still
+		// overflows.
 		//
-		// The latch exists so that a second overflow immediately after a
-		// successful compaction — meaning the prompt is irreducible — stops
-		// instead of looping. It was never meant to disarm the mechanism for
-		// the rest of the turn, which is what a turn-scoped flag did: one
-		// relief at iteration 3 left iteration 40 to die on an overflow with
-		// obvious moves left. It is cleared by a turn that actually
-		// succeeded, which is the evidence that the turn is no longer stuck.
-		let overflowRelieved = false
+		// The limit exists so that an overflow that survives both rungs — an
+		// irreducible prompt — stops instead of looping. It was never meant to
+		// disarm the mechanism for the rest of the turn, which is what a
+		// turn-scoped flag did: one relief at iteration 3 left iteration 40 to die
+		// on an overflow with obvious moves left. The count is cleared by a turn
+		// that actually succeeded, which is the evidence that the turn is no
+		// longer stuck.
+		let overflowReliefs = 0
+		// The output cap a provider told us fits beside this prompt. One request's
+		// worth: it is cleared by a call that went through.
+		let outputCapOverride: number | undefined
 
 		// A `finally` rather than a line at each exit, for the reason written
 		// beside `iterSpan.end()` below: this loop leaves by eight `break`s,
@@ -573,12 +739,15 @@ export class IterationOrchestrator {
 						yield* this.ctx.drainPending()
 					}
 
+					if (!forceFinalize) await this.deliverReminders(iterationNum)
+
 					// Re-pin the working-memory block from ground truth at the primacy
 					// edge BEFORE compaction runs (so the refreshed slot is what
 					// compaction preserves). No-op when no provider is configured.
 					await refreshWorkingMemory(this.ctx)
 					await runCompactionCheck(this.ctx)
 					yield* this.ctx.drainPending()
+					if (this.stopForCompactionBreaker()) break
 
 					// Cache discipline: keep the tools param byte-stable even on the
 					// forced-final iteration and forbid tool use via tool_choice
@@ -630,6 +799,7 @@ export class IterationOrchestrator {
 					if (stepModel !== contextModelBeforePreparation) await runCompactionCheck(this.ctx)
 					// Publish context edits before entering a possibly slow provider.
 					yield* this.ctx.drainPending()
+					if (this.stopForCompactionBreaker()) break
 
 					const stepAllowedTools = step.allowedTools ?? this.ctx.allowedTools
 					const deferredMcpContext = deferredMcpHints?.forNames(stepAllowedTools) ?? ''
@@ -730,6 +900,7 @@ export class IterationOrchestrator {
 						this.projectObservations(requestHistory),
 						this.ctx.turnConfig.maxRequestRichContentBytes ??
 							DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
+						{ imagesReadable: this.modelReadsImages(stepModel) },
 					)
 					appendWorkContext(shaping, messages, iterationNum, step)
 					if (closingDirective) messages.push(closingDirective)
@@ -808,7 +979,8 @@ export class IterationOrchestrator {
 									messages: Object.freeze(messages.map((m) => Object.freeze({ ...m }))),
 									toolNames: Object.freeze(llmTools.map((t) => t.function.name)),
 									temperature: step.temperature ?? turnConfig.temperature,
-									maxTokens: step.maxResponseTokens ?? turnConfig.maxResponseTokens,
+									maxTokens:
+										outputCapOverride ?? step.maxResponseTokens ?? turnConfig.maxResponseTokens,
 								}),
 							},
 							this.ctx.emitEvent,
@@ -881,7 +1053,8 @@ export class IterationOrchestrator {
 										? step.toolChoice
 										: undefined,
 							temperature: step.temperature ?? turnConfig.temperature,
-							maxTokens: step.maxResponseTokens ?? turnConfig.maxResponseTokens,
+							maxTokens:
+								outputCapOverride ?? step.maxResponseTokens ?? turnConfig.maxResponseTokens,
 							cacheControl: { type: 'auto' },
 							...(turnConfig.thinking ? { thinking: turnConfig.thinking } : {}),
 							...(turnConfig.effort ? { effort: turnConfig.effort } : {}),
@@ -903,6 +1076,8 @@ export class IterationOrchestrator {
 						stepMessageId,
 						{
 							onAccepted: (identity) => this.acceptProviderRejectedImage(identity),
+							textOnly: this.textOnlyRecovery(stepModel),
+							repair: this.requestRepair,
 						},
 						Boolean(
 							this.ctx.reviewAnswer || this.ctx.structuredOutput?.review || this.ctx.advisoryCtx,
@@ -956,7 +1131,10 @@ export class IterationOrchestrator {
 
 					// The turn went through, so the turn is not sitting on an
 					// irreducible prompt any more. Re-arm relief for the next one.
-					overflowRelieved = false
+					overflowReliefs = 0
+					clearCompactionErrorNote(this.ctx)
+					outputCapOverride = undefined
+					if (response.finishReason !== 'length') this.outputContinuations = 0
 
 					if (this.ctx.pluginManager) {
 						const hookResults = await this.ctx.pluginManager.executeHooks(
@@ -1283,19 +1461,55 @@ export class IterationOrchestrator {
 						//     it has no room left to continue into, and the
 						//     continuation would only send a longer prompt into
 						//     the same full window. The reply stands as it is.
+						const cutDuringReasoning =
+							!hasContent &&
+							(response.message.toolCalls?.length ?? 0) === 0 &&
+							(response.message.reasoning?.length ?? 0) > 0
 						if (
 							!forceFinalize &&
 							response.finishReason === 'length' &&
 							response.finishDetail !== 'context_window' &&
-							hasContent
+							(hasContent || cutDuringReasoning)
 						) {
-							this.ctx.log.info('LLM hit max_tokens mid-text — auto-continuing', {
-								[NAMZU.TURN_ID]: recorder.turnId,
-								[NAMZU.ITERATION]: iterationNum,
-								[GENAI.USAGE_OUTPUT_TOKENS]: response.usage.completionTokens,
-							})
+							// A host that opted in gets a cap on the nudges: a model that
+							// overruns its output limit every time would otherwise spend the
+							// whole turn on it. Past the cap the turn stops, and says why.
+							const cap = this.ctx.maxOutputContinuations
+							if (cap !== undefined && this.outputContinuations >= cap) {
+								this.ctx.log.warn('LLM kept hitting max_tokens — stopping the turn', {
+									[NAMZU.TURN_ID]: recorder.turnId,
+									[NAMZU.ITERATION]: iterationNum,
+									'namzu.runtime.output_continuations': this.outputContinuations,
+								})
+								recorder.setLastError(
+									`The reply was cut off at the output limit ${cap + 1} times in a row. Ask for a smaller piece of the work, or raise the output limit.`,
+								)
+								recorder.setStopReason('output_limit')
+								await this.ctx.emitEvent({
+									type: 'iteration_completed',
+									turnId: recorder.turnId,
+									iteration: iterationNum,
+									hasToolCalls: false,
+								})
+								yield* this.ctx.drainPending()
+								break
+							}
+							this.outputContinuations++
+							this.ctx.log.info(
+								cutDuringReasoning
+									? 'LLM hit max_tokens while reasoning — nudging to answer briefly'
+									: 'LLM hit max_tokens mid-text — auto-continuing',
+								{
+									[NAMZU.TURN_ID]: recorder.turnId,
+									[NAMZU.ITERATION]: iterationNum,
+									[GENAI.USAGE_OUTPUT_TOKENS]: response.usage.completionTokens,
+								},
+							)
 							recorder.pushMessage(
-								createRuntimeContextMessage(AUTO_CONTINUATION_USER_MESSAGE, 'auto-continuation'),
+								createRuntimeContextMessage(
+									cutDuringReasoning ? REASONING_CUT_USER_MESSAGE : AUTO_CONTINUATION_USER_MESSAGE,
+									'auto-continuation',
+								),
 							)
 							await this.ctx.emitEvent({
 								type: 'iteration_completed',
@@ -1451,6 +1665,27 @@ export class IterationOrchestrator {
 						// also settle as `end_turn`, and there the deferred predicate
 						// is not why the turn ended: those decided the answer
 						// themselves.
+						// The model is done and has no tool calls. A `turn_end` (or
+						// `subagent_stop`) hook may refuse to let it be: its reason goes
+						// back to the model and the turn goes on.
+						if (!forceFinalize && closingStopReason === undefined) {
+							const feedback = yield* this.askStopHooks()
+							const stoppedByHook = this.ctx.toolExecutor.takeHalt?.()
+							if (stoppedByHook !== undefined) {
+								recorder.setLastError(`Stopped by a hook: ${stoppedByHook}`)
+								recorder.setStopReason('stop_condition')
+								break
+							}
+							if (feedback !== undefined) {
+								recorder.pushMessage(
+									createRuntimeContextMessage(
+										`A hook asked for more before this turn ends:\n${feedback}`,
+										'hook-feedback',
+									),
+								)
+								continue
+							}
+						}
 						recorder.setStopReason(
 							closingStopReason ??
 								(stopWasDeferredForOutstandingWork ? 'stop_condition' : 'end_turn'),
@@ -1495,6 +1730,28 @@ export class IterationOrchestrator {
 						return
 					}
 
+					// A hook asked for the turn to stop once this step's calls were
+					// answered. Every `tool_use` has its `tool_result` by now, so the
+					// transcript is whole; what is left is to end the turn and say why.
+					const hookHalt = this.ctx.toolExecutor.takeHalt?.()
+					if (hookHalt !== undefined) {
+						this.ctx.log.info('A hook stopped the turn', {
+							[NAMZU.TURN_ID]: recorder.turnId,
+							[NAMZU.ITERATION]: iterationNum,
+							'namzu.hook.reason': hookHalt,
+						})
+						recorder.setLastError(`Stopped by a hook: ${hookHalt}`)
+						recorder.setStopReason('stop_condition')
+						await this.ctx.emitEvent({
+							type: 'iteration_completed',
+							turnId: recorder.turnId,
+							iteration: iterationNum,
+							hasToolCalls: true,
+						})
+						yield* this.ctx.drainPending()
+						break
+					}
+
 					if (reviewOutcome.decision === 'rejected') {
 						continue
 					}
@@ -1728,6 +1985,12 @@ export class IterationOrchestrator {
 					yield* this.ctx.drainPending()
 				} catch (err) {
 					const cancelled = this.ctx.abortController.signal.aborted
+					// A deferred sandbox that was cancelled or ran out of time. The
+					// turn settles it as `cancelled` / `timeout` in `query()`, which is
+					// not a failure of this iteration: it is recorded the way a turn
+					// stopped by its own abort or timeout is (a cancelled step, no
+					// error span), so the ledger and the stop reason agree.
+					const sandboxStopped = err instanceof SandboxAcquisitionStopped
 
 					// This iteration gets a step too, and it is the one the
 					// argument three hundred lines above was actually about.
@@ -1788,12 +2051,13 @@ export class IterationOrchestrator {
 							startedAt: stepStartedAt,
 							usageBefore,
 							costBefore,
-							unfinished: cancelled
-								? { finishReason: 'cancelled' }
-								: {
-										finishReason: 'error',
-										failure: describeStepFailure(err, this.ctx.provider.id),
-									},
+							unfinished:
+								cancelled || sandboxStopped
+									? { finishReason: 'cancelled' }
+									: {
+											finishReason: 'error',
+											failure: describeStepFailure(err, this.ctx.provider.id),
+										},
 						})
 					}
 
@@ -1822,23 +2086,89 @@ export class IterationOrchestrator {
 					// actually shed something. A second overflow after a successful
 					// compaction means the prompt is irreducible, and looping on it
 					// would burn the budget to arrive at the same error.
+					// The prompt fit and only the requested output did not: ask for what
+					// room is left (less a margin) and send it again, once. A reply that
+					// would be too small to be useful, or a cap that is not smaller than
+					// the one already tried, is not retried: the same failure would follow.
+					const outputOverflow =
+						err instanceof AnswerReviewFailure ? undefined : readOutputOverflow(err)
+					if (outputOverflow) {
+						const room = Math.max(
+							0,
+							outputOverflow.contextLimit - outputOverflow.inputTokens - OUTPUT_CAP_MARGIN_TOKENS,
+						)
+						if (
+							room >= MIN_OUTPUT_CAP_TOKENS &&
+							(outputCapOverride === undefined || room < outputCapOverride)
+						) {
+							outputCapOverride = room
+							this.ctx.log.info('Output cap does not fit beside the prompt — retrying with less', {
+								[NAMZU.TURN_ID]: recorder.turnId,
+								[NAMZU.ITERATION]: iterationNum,
+								'namzu.runtime.input_tokens': outputOverflow.inputTokens,
+								'namzu.runtime.context_limit': outputOverflow.contextLimit,
+								'namzu.runtime.adjusted_max_tokens': room,
+							})
+							if (iterationActivity) {
+								this.ctx.activityStore.complete(iterationActivity.id)
+							}
+							continue
+						}
+					}
+
 					if (
-						!overflowRelieved &&
 						!(err instanceof AnswerReviewFailure) &&
 						classifyProviderError(err, this.ctx.provider.id).code === 'context_length_exceeded'
 					) {
-						overflowRelieved = true
-						const shed = await relieveOverflow(this.ctx)
+						// The rapid-refill check comes first, before the first reactive relief
+						// of an overflow, as in the reference terminal. A relief that follows
+						// the previous compaction within the refill window counts toward the
+						// limit, so a tool that re-fills the window every time it is called
+						// stops the turn instead of being cleared and called again without end.
+						// The deeper rung of the same overflow is not counted again.
+						if (overflowReliefs === 0 && (await stopOnRefill(this.ctx))) {
+							if (iterationActivity) {
+								this.ctx.activityStore.fail(iterationActivity.id, toErrorMessage(err))
+							}
+							if (this.stopForCompactionBreaker()) break
+						}
+						// A rung that sheds too little to change the verdict is not worth a
+						// provider call; climb to the next one at once.
+						let shed = false
+						while (!shed && overflowReliefs < OVERFLOW_RELIEF_LIMIT) {
+							overflowReliefs++
+							shed = await relieveOverflow(this.ctx, { deeper: overflowReliefs > 1 })
+						}
 						if (shed) {
+							// Clearing results is a compaction too: only summaries and reducers
+							// recorded themselves, so a clear-only relief was invisible to the
+							// breaker.
+							compactionBreaker(this.ctx)?.recordCompaction(iterationNum)
 							this.ctx.log.info('Retrying the turn after relieving a context overflow', {
 								[NAMZU.TURN_ID]: recorder.turnId,
 								[NAMZU.ITERATION]: iterationNum,
+								'namzu.runtime.relief_rung': overflowReliefs,
 							})
 							if (iterationActivity) {
 								this.ctx.activityStore.complete(iterationActivity.id)
 							}
 							continue
 						}
+						// Out of rungs. The conversation is kept; say why compaction could not
+						// make room when it errored, as the reference does.
+						const cause = compactionErrorNote(this.ctx)
+						if (cause !== undefined && err instanceof Error) {
+							try {
+								err.message = `${err.message}${AUTOMATIC_COMPACTION_FAILED}${cause}`
+							} catch {
+								// A frozen error keeps its own message; the cause stays in the log.
+							}
+						}
+					}
+
+					if (sandboxStopped) {
+						if (iterationActivity) this.ctx.activityStore.complete(iterationActivity.id)
+						throw err
 					}
 
 					if (iterationActivity) {
@@ -1925,6 +2255,39 @@ export class IterationOrchestrator {
 		}
 	}
 
+	/**
+	 * Ask the host's reminder source (`QueryParams.reminders`) what the model
+	 * should be told before this request, and append each text as a hidden
+	 * user-role message. The start of a request is a provider-valid boundary:
+	 * the history ends in the operator's message or in a finished tool batch.
+	 * A source that throws has nothing to say; it never fails the turn.
+	 */
+	private async deliverReminders(iteration: number): Promise<void> {
+		const source = this.ctx.reminders
+		if (!source) return
+		const { recorder } = this.ctx
+		let texts: readonly string[] | undefined
+		try {
+			texts = await source({
+				sessionId: recorder.sessionId,
+				turnId: recorder.turnId,
+				iteration,
+				messages: recorder.messages,
+			})
+		} catch (error) {
+			this.ctx.log.warn('A reminder source threw; the request goes without its reminders', {
+				[NAMZU.TURN_ID]: recorder.turnId,
+				[NAMZU.ITERATION]: iteration,
+				'exception.message': error instanceof Error ? error.message : String(error),
+			})
+			return
+		}
+		for (const text of texts ?? []) {
+			if (text.trim().length === 0) continue
+			recorder.pushMessage(createRuntimeContextMessage(text, 'reminder'))
+		}
+	}
+
 	private async deliverInbound(): Promise<number> {
 		const queued = this.ctx.inboundMessages?.() ?? []
 		for (const message of queued) {
@@ -2078,6 +2441,15 @@ export class IterationOrchestrator {
 		return true
 	}
 
+	/** The compaction circuit breaker asked for the turn to stop (opt-in; see `compactionConfig.circuitBreaker`). */
+	private stopForCompactionBreaker(): boolean {
+		const reason = compactionBreaker(this.ctx)?.stop
+		if (reason === undefined) return false
+		this.ctx.recorder.setLastError(reason)
+		this.ctx.recorder.setStopReason('error')
+		return true
+	}
+
 	private async recordToolStructuredFailure(
 		results: readonly ToolCallOutcome[],
 		iteration: number,
@@ -2404,6 +2776,32 @@ export class IterationOrchestrator {
 			.some((t) => t.state !== 'completed' && t.state !== 'failed' && t.state !== 'canceled')
 	}
 
+	/** Media the provider could not process was left out of a request that then went through. */
+	private async noteMediaRemoved(removal: MediaRemoval): Promise<void> {
+		this.ctx.log.warn('Media the provider rejected was left out of the request', {
+			[GENAI.SYSTEM]: this.ctx.provider.id,
+			'namzu.request.media_removed': removal.count,
+		})
+		const noun = removal.count === 1 ? 'a file' : `${removal.count} files`
+		const it = removal.count === 1 ? 'it' : 'they'
+		await this.ctx.emitEvent?.({
+			type: 'capability_warning',
+			turnId: this.ctx.recorder.turnId,
+			capability: removal.kind === 'document' ? 'documents' : 'vision',
+			// The person's own latest attachment is named as such; a count limit is
+			// not a fault in any file.
+			contentSource: removal.current
+				? 'media-removed-current'
+				: removal.limit
+					? 'media-limit'
+					: 'media-removed',
+			providerId: this.ctx.provider.id,
+			message: removal.limit
+				? `The conversation holds more files than the provider accepts at once, so ${noun} (the oldest) ${removal.count === 1 ? 'was' : 'were'} left out of the request. The conversation still holds ${it}.`
+				: `The provider could not process ${noun}${removal.current ? ' attached to your latest message' : ' in this conversation'}, so ${it} ${removal.count === 1 ? 'was' : 'were'} left out of the request. The conversation still holds ${it}.`,
+		})
+	}
+
 	private async acceptProviderRejectedImage(identity: RequestImageIdentity): Promise<void> {
 		const repaired = markProviderRejectedImage(this.ctx.recorder.messages, identity)
 		if (repaired.count === 0) {
@@ -2461,6 +2859,7 @@ export class IterationOrchestrator {
 			const finalMessages = projectRequestRichContent(
 				this.projectObservations(finalHistory),
 				this.ctx.turnConfig.maxRequestRichContentBytes ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
+				{ imagesReadable: this.modelReadsImages(model) },
 			)
 			appendWorkContext(this.stepShaping(), finalMessages, this.steps.length + 1, { model })
 			// The closing directive is the last thing the model reads: after
@@ -2507,8 +2906,13 @@ export class IterationOrchestrator {
 				signal: this.ctx.abortController.signal,
 			} satisfies import('../../../types/provider/index.js').ChatCompletionParams
 			const response = await collectChatCompletion(
-				streamWithProviderRejectedImageRecovery(this.ctx.provider, finalParams, (identity) =>
-					this.acceptProviderRejectedImage(identity),
+				streamWithProviderRejectedImageRecovery(
+					this.ctx.provider,
+					finalParams,
+					(identity) => this.acceptProviderRejectedImage(identity),
+					undefined,
+					this.textOnlyRecovery(model),
+					this.requestRepair,
 				),
 			)