@namzu/sdk 52.0.0 → 52.1.0

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

@@ -6,7 +6,7 @@ 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';
@@ -21,6 +21,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 { projectObservationContext } from '../observation-context.js';
 import { applyLifecycleHookResults } from '../plugin-hooks.js';
@@ -32,12 +33,13 @@ import { drainArrivedTaskCompletions, holdForOutstandingWork, settleOutstandingW
 import { runAdvisoryPhase } from './phases/advisory.js';
 import { runIterationCheckpoint } from './phases/checkpoint.js';
 import { compactionBreaker } from './phases/compaction-breaker.js';
-import { activeContextWindow, measureContext, relieveOverflow, runCompactionCheck, } from './phases/compaction.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. */
@@ -69,6 +71,10 @@ const MIN_OUTPUT_CAP_TOKENS = 3000;
 // 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;
@@ -103,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.
      *
@@ -330,16 +398,19 @@ 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;
@@ -662,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);
@@ -814,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 = {
@@ -859,7 +932,8 @@ 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;
@@ -1591,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.
                     //
@@ -1651,7 +1731,7 @@ export class IterationOrchestrator {
                             startedAt: stepStartedAt,
                             usageBefore,
                             costBefore,
-                            unfinished: cancelled
+                            unfinished: cancelled || sandboxStopped
                                 ? { finishReason: 'cancelled' }
                                 : {
                                     finishReason: 'error',
@@ -1706,21 +1786,59 @@ export class IterationOrchestrator {
                             continue;
                         }
                     }
-                    if (!overflowRelieved &&
-                        !(err instanceof AnswerReviewFailure) &&
+                    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));
@@ -2257,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) {
@@ -2301,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.
@@ -2340,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,