@namzu/sdk 51.1.0 → 52.1.0

package/dist/runtime/query/iteration/index.js

@@ -1,12 +1,12 @@
 import { SpanStatusCode } from '@opentelemetry/api';
 import { extractFromAssistantMessage, 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, STRUCTURED_OUTPUT_REPROMPT, } 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';
@@ -15,12 +15,13 @@ import { getTracer } from '../../../telemetry/runtime-accessors.js';
 import { STRUCTURED_OUTPUT_TOOL_NAME } from '../../../tools/builtins/structuredOutput.js';
 import { NamzuError } from '../../../types/errors/index.js';
 import { createAssistantMessage, createRuntimeContextMessage, createSystemMessage, } from '../../../types/message/index.js';
-import { classifyProviderError } from '../../../types/provider/errors.js';
+import { classifyProviderError, readOutputOverflow } from '../../../types/provider/errors.js';
 import { toErrorMessage } from '../../../utils/error.js';
 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 { projectObservationContext } from '../observation-context.js';
 import { applyLifecycleHookResults } from '../plugin-hooks.js';
@@ -31,12 +32,14 @@ import { parseNativeCandidate } from './native-output.js';
 import { drainArrivedTaskCompletions, holdForOutstandingWork, settleOutstandingWork, } from './outstanding-work.js';
 import { runAdvisoryPhase } from './phases/advisory.js';
 import { runIterationCheckpoint } from './phases/checkpoint.js';
-import { activeContextWindow, measureContext, relieveOverflow, runCompactionCheck, } from './phases/compaction.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 { 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 { streamWithProviderRejectedImageRecovery, } from './provider-rejected-image.js';
+import { RequestRepair } from './request-repair.js';
 import { appendWorkContext, beforeStep, prepareStep, selectContextModel, stepContextMessage, } from './step-shaping.js';
 import { streamProviderTurn } from './stream-turn.js';
 /** A host reviewer is not the model transport, even when its cause is an HTTP failure. */
@@ -60,10 +63,18 @@ class AnswerReviewFailure extends NamzuError {
  * on the thing that actually went wrong.
  */
 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 = 'Give a concise response using only what the available evidence supports. Attribute unverified statements to their source instead of presenting them as observed facts. If evidence is missing or conflicting, state what cannot be established. Do not claim unfinished work is complete. Do not request any more tool calls.';
 export { awaitedJobGraceMs, settleGraceMs } from './outstanding-work.js';
+/** One provider's model, as {@link IterationOrchestrator} remembers it. */
+function textOnlyKey(providerId, model) {
+    return `${providerId}\u0000${model}`;
+}
 export class IterationOrchestrator {
     ctx;
     advisoryTurn;
@@ -98,6 +109,68 @@ export class IterationOrchestrator {
     }
     /** Rich tool blocks already reported; durable history is scanned every turn. */
     warnedRichToolResults = new Set();
+    /** What this run has learned about requests its provider rejects as invalid, and how to repair them. */
+    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.
+     */
+    textOnlyModels = new Set();
+    /**
+     * 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.
+     */
+    servingModel(model) {
+        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. */
+    modelReadsImages(model) {
+        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. */
+    textOnlyRecovery(model) {
+        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.
+     */
+    async noteTextOnlyModel(refused) {
+        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.
      *
@@ -113,6 +186,67 @@ export class IterationOrchestrator {
      * sets it.
      */
     stopDeferredForOutstandingWork = false;
+    /** Nudges sent since the model last finished a call without hitting its output cap. */
+    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.
+     */
+    turnEndFired = false;
+    /** A hook already kept this turn going once: it is asked again with `stop_hook_active`. */
+    stopHookActive = false;
+    get turnEndHooksFired() {
+        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.
+     */
+    async *askStopHooks() {
+        const manager = this.ctx.pluginManager;
+        if (!manager)
+            return undefined;
+        const recorder = this.ctx.recorder;
+        const feedback = [];
+        const ask = async (event, extra) => {
+            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. */
     latestUserMessage;
     initialDurableDelivered = false;
@@ -264,16 +398,22 @@ export class IterationOrchestrator {
         // paused it. Taken after the intent above is known, so the
         // 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;
         // A `finally` rather than a line at each exit, for the reason written
         // beside `iterSpan.end()` below: this loop leaves by eight `break`s,
         // two `return`s and a `throw`, and a rule every future edit has to
@@ -446,12 +586,16 @@ export class IterationOrchestrator {
                         applyLifecycleHookResults('iteration_start', hookResults);
                         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
                     // 'none' instead. Dropping the tools array would invalidate the
@@ -498,6 +642,8 @@ export class IterationOrchestrator {
                         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) ?? '';
                     const contextText = [
@@ -587,7 +733,7 @@ export class IterationOrchestrator {
                     if (step.context)
                         requestHistory.push(stepContextMessage(step.context));
                     const messages = projectRequestRichContent(this.projectObservations(requestHistory), this.ctx.turnConfig.maxRequestRichContentBytes ??
-                        DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES);
+                        DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES, { imagesReadable: this.modelReadsImages(stepModel) });
                     appendWorkContext(shaping, messages, iterationNum, step);
                     if (closingDirective)
                         messages.push(closingDirective);
@@ -660,7 +806,7 @@ 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);
                         applyLifecycleHookResults('pre_llm_call', hookResults);
@@ -726,7 +872,7 @@ 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 } : {}),
@@ -739,6 +885,8 @@ export class IterationOrchestrator {
                         signal: this.ctx.abortController.signal,
                     }, this.ctx.emitEvent, this.ctx.drainPending, recorder.turnId, iterationNum, forceFinalize, this.ctx.log, iterSpan, stepMessageId, {
                         onAccepted: (identity) => this.acceptProviderRejectedImage(identity),
+                        textOnly: this.textOnlyRecovery(stepModel),
+                        repair: this.requestRepair,
                     }, Boolean(this.ctx.reviewAnswer || this.ctx.structuredOutput?.review || this.ctx.advisoryCtx), recorder.sessionId);
                     stepResponse = response;
                     const reviewRequest = {
@@ -784,7 +932,11 @@ 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('post_llm_call', {
                             sessionId: recorder.sessionId,
@@ -1055,16 +1207,43 @@ 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) {
-                            this.ctx.log.info('LLM hit max_tokens mid-text — auto-continuing', {
+                            (hasContent || cutDuringReasoning)) {
+                            // 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'));
+                            recorder.pushMessage(createRuntimeContextMessage(cutDuringReasoning ? REASONING_CUT_USER_MESSAGE : AUTO_CONTINUATION_USER_MESSAGE, 'auto-continuation'));
                             await this.ctx.emitEvent({
                                 type: 'iteration_completed',
                                 turnId: recorder.turnId,
@@ -1206,6 +1385,22 @@ 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'));
                         break;
@@ -1240,6 +1435,27 @@ export class IterationOrchestrator {
                     if ((yield* runHandoffPause(this.ctx, iterationNum, reviewOutcome.results)) === 'stop') {
                         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;
                     }
@@ -1449,6 +1665,12 @@ export class IterationOrchestrator {
                 }
                 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.
                     //
@@ -1509,7 +1731,7 @@ export class IterationOrchestrator {
                             startedAt: stepStartedAt,
                             usageBefore,
                             costBefore,
-                            unfinished: cancelled
+                            unfinished: cancelled || sandboxStopped
                                 ? { finishReason: 'cancelled' }
                                 : {
                                     finishReason: 'error',
@@ -1541,21 +1763,82 @@ 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.
-                    if (!overflowRelieved &&
-                        !(err instanceof AnswerReviewFailure) &&
+                    // 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 (!(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) {
                         this.ctx.activityStore.fail(iterationActivity.id, toErrorMessage(err));
@@ -1639,6 +1922,41 @@ export class IterationOrchestrator {
             extractFromUserMessage(manager, message.content, !manager.getState().task);
         }
     }
+    /**
+     * 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.
+     */
+    async deliverReminders(iteration) {
+        const source = this.ctx.reminders;
+        if (!source)
+            return;
+        const { recorder } = this.ctx;
+        let texts;
+        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'));
+        }
+    }
     async deliverInbound() {
         const queued = this.ctx.inboundMessages?.() ?? [];
         for (const message of queued) {
@@ -1756,6 +2074,15 @@ export class IterationOrchestrator {
         recorder.setStopReason('structured_output_failed');
         return true;
     }
+    /** The compaction circuit breaker asked for the turn to stop (opt-in; see `compactionConfig.circuitBreaker`). */
+    stopForCompactionBreaker() {
+        const reason = compactionBreaker(this.ctx)?.stop;
+        if (reason === undefined)
+            return false;
+        this.ctx.recorder.setLastError(reason);
+        this.ctx.recorder.setStopReason('error');
+        return true;
+    }
     async recordToolStructuredFailure(results, iteration) {
         if (!this.needsStructuredOutput() ||
             this.ctx.structuredOutput?.mode === 'native' ||
@@ -2048,6 +2375,31 @@ export class IterationOrchestrator {
             .listTasks()
             .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. */
+    async noteMediaRemoved(removal) {
+        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}.`,
+        });
+    }
     async acceptProviderRejectedImage(identity) {
         const repaired = markProviderRejectedImage(this.ctx.recorder.messages, identity);
         if (repaired.count === 0) {
@@ -2092,7 +2444,7 @@ export class IterationOrchestrator {
                 ...workingMemory.history,
                 ...(workingMemory.context ? [workingMemory.context] : []),
             ];
-            const finalMessages = projectRequestRichContent(this.projectObservations(finalHistory), this.ctx.turnConfig.maxRequestRichContentBytes ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES);
+            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
             // the working memory and any work context above.
@@ -2131,7 +2483,7 @@ export class IterationOrchestrator {
                 // stream to completion.
                 signal: this.ctx.abortController.signal,
             };
-            const response = await collectChatCompletion(streamWithProviderRejectedImageRecovery(this.ctx.provider, finalParams, (identity) => this.acceptProviderRejectedImage(identity)));
+            const response = await collectChatCompletion(streamWithProviderRejectedImageRecovery(this.ctx.provider, finalParams, (identity) => this.acceptProviderRejectedImage(identity), undefined, this.textOnlyRecovery(model), this.requestRepair));
             const servingMember = this.ctx.servingMember?.() ?? requestedMember;
             const servedBy = {
                 providerId: servingMember.providerId,