@namzu/sdk 60.0.0 → 60.2.0

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

@@ -1,7 +1,7 @@
 import { SpanStatusCode } from '@opentelemetry/api';
 import { extractFromAssistantMessage, extractFromUserMessage, } from '../../../compaction/extractor.js';
 import { estimateMessageTokens } from '../../../compaction/token-estimate.js';
-import { AUTO_CONTINUATION_USER_MESSAGE, REASONING_CUT_USER_MESSAGE, } from '../../../constants/continuation.js';
+import { AUTO_CONTINUATION_USER_MESSAGE, REASONING_CUT_USER_MESSAGE, REFUSED_REPLY_CALL_RESULT, REFUSED_REPLY_RETRY_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';
@@ -14,7 +14,7 @@ import { GENAI, NAMZU, agentIterationSpanName, parentContext, } from '../../../t
 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 { createAssistantMessage, createRuntimeContextMessage, createSystemMessage, createToolMessage, } from '../../../types/message/index.js';
 import { classifyProviderError, readOutputOverflow } from '../../../types/provider/errors.js';
 import { toErrorMessage } from '../../../utils/error.js';
 import { stableDigest } from '../../../utils/hash.js';
@@ -28,6 +28,7 @@ import { applyLifecycleHookResults } from '../plugin-hooks.js';
 import { diffRequestContext, snapshotRequestContext, } from '../request-context.js';
 import { DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES, markProviderRejectedImage, projectRequestRichContent, } from '../request-rich-content.js';
 import { formatSteeringNote, isOperatorUserMessage } from '../steering.js';
+import { effortForModel } from './effort-clamp.js';
 import { parseNativeCandidate } from './native-output.js';
 import { drainArrivedTaskCompletions, holdForOutstandingWork, settleOutstandingWork, } from './outstanding-work.js';
 import { runAdvisoryPhase } from './phases/advisory.js';
@@ -191,6 +192,16 @@ export class IterationOrchestrator {
     stopDeferredForOutstandingWork = false;
     /** Nudges sent since the model last finished a call without hitting its output cap. */
     outputContinuations = 0;
+    /**
+     * The model a refused request moved to. Once set it replaces the model the
+     * step asked for, for the rest of the turn: the request that was refused
+     * would only be refused again.
+     */
+    refusalPinnedModel;
+    /** The request has already been re-run on another model once this turn. */
+    refusalFallbackUsed = false;
+    /** The request has already been re-run on the same model once this turn. */
+    refusalRetryUsed = false;
     /**
      * `turn_end` (and, for a child, `subagent_stop`) fired when the model
      * finished and no hook asked for more. `finalizeTurn` then does not fire
@@ -637,7 +648,7 @@ export class IterationOrchestrator {
                     // Preparation inference belongs to the turn, not the main-model step.
                     usageBefore = { ...recorder.tokenUsage };
                     costBefore = { ...recorder.costInfo };
-                    stepModel = step.model ?? model;
+                    stepModel = this.refusalPinnedModel ?? step.model ?? model;
                     await selectContextModel(shaping, stepModel);
                     // Preserve post-compaction preparation/recall semantics. A changed
                     // model needs a second check against its own window; never replay
@@ -664,7 +675,7 @@ export class IterationOrchestrator {
                     // still call any of them by name.
                     this.ctx.toolExecutor.setStepAllowedTools(stepAllowedTools);
                     const enforceToolInputSchema = enforcedModelInputToolNames(this.ctx.tools, llmTools);
-                    stepModel = step.model ?? model;
+                    stepModel = this.refusalPinnedModel ?? step.model ?? model;
                     // The closing directive is appended LAST, after every piece of
                     // request-only context below, so it is the final thing the model
                     // reads on a forced-final step.
@@ -869,6 +880,20 @@ export class IterationOrchestrator {
                         model: requestedMember.model ?? stepModel,
                         chainIndex: requestedMember.index,
                     };
+                    // The turn's effort was chosen for the turn's own model. A request
+                    // moved to another model (a refusal fallback, a live pick) carries
+                    // the nearest level that model offers, for this request only.
+                    let requestEffort = turnConfig.effort;
+                    if (requestEffort && stepModel !== model) {
+                        requestEffort = effortForModel(this.ctx.provider, stepModel, requestEffort, turnConfig.thinking);
+                        if (requestEffort !== turnConfig.effort) {
+                            this.ctx.log.debug('Effort lowered to a level this model offers', {
+                                'namzu.runtime.model': stepModel,
+                                'namzu.runtime.effort_requested': turnConfig.effort,
+                                'namzu.runtime.effort_used': requestEffort,
+                            });
+                        }
+                    }
                     const operatorInputAtDispatch = this.latestUserMessage;
                     const latestReviewUserMessage = (this.ctx.reviewAnswer || this.ctx.structuredOutput?.review) && operatorInputAtDispatch
                         ? structuredClone(operatorInputAtDispatch)
@@ -905,7 +930,7 @@ export class IterationOrchestrator {
                         maxTokens: outputCapOverride ?? step.maxResponseTokens ?? turnConfig.maxResponseTokens,
                         cacheControl: { type: 'auto' },
                         ...(turnConfig.thinking ? { thinking: turnConfig.thinking } : {}),
-                        ...(turnConfig.effort ? { effort: turnConfig.effort } : {}),
+                        ...(requestEffort ? { effort: requestEffort } : {}),
                         ...(!forceFinalize && turnConfig.webSearch
                             ? { webSearch: turnConfig.webSearch }
                             : {}),
@@ -1032,6 +1057,34 @@ export class IterationOrchestrator {
                             : {}),
                         ...contextFigures,
                     });
+                    // A reply the provider declined to give is its own case. It is not
+                    // an empty completion: asking again with the same history on the
+                    // same model is refused again, at the full price of the prompt.
+                    // Recovered here, before the reply can enter the history.
+                    if (response.finishReason === 'content_filter') {
+                        iterSpan.setStatus({ code: SpanStatusCode.OK });
+                        if (iterationActivity) {
+                            this.ctx.activityStore.complete(iterationActivity.id, {
+                                content: response.message.content,
+                                hasToolCalls: false,
+                            });
+                        }
+                        const outcome = yield* this.recoverFromRefusal({
+                            response,
+                            messageId,
+                            stepModel,
+                            servedBy,
+                            forceFinalize,
+                            limitStopReason: forceFinalize ? guardResult.stopReason : undefined,
+                            iterationNum,
+                            stepStartedAt,
+                            usageBefore,
+                            costBefore,
+                        });
+                        if (outcome === 'retry')
+                            continue;
+                        break;
+                    }
                     // Durable reasoning and its adapter-private replay envelope ride
                     // with the turn they belong to. Trimming therefore removes both;
                     // retaining them gives the target adapter enough evidence to
@@ -1396,7 +1449,7 @@ export class IterationOrchestrator {
                                 [NAMZU.ITERATION]: iterationNum,
                                 'namzu.runtime.finish_reason': response.finishReason,
                             });
-                            closingStopReason = await this.requestFinalResponse(model, 'end_turn');
+                            closingStopReason = await this.requestFinalResponse(this.refusalPinnedModel ?? model, 'end_turn');
                             yield* this.ctx.drainPending();
                         }
                         await this.ctx.emitEvent({
@@ -2460,6 +2513,137 @@ export class IterationOrchestrator {
             providerRejectedImagesSuppressed: repaired.count,
         });
     }
+    /**
+     * A reply the provider declined to give.
+     *
+     * The refused reply never enters the history sent next, except on the
+     * same-model retry, where the stopped partial reply stays so the model can
+     * see what to avoid. At most one automatic retry of each kind per turn:
+     *
+     * 1. Another model of the same provider, when the provider names one and
+     *    the host has not turned `refusalFallback` off. The model is kept for
+     *    the rest of the turn and announced in a `model_refusal` event.
+     * 2. The same model once more, only when the refused reply had partial
+     *    text or tool calls: unfinished calls get an error result and the
+     *    model is told the reply was stopped.
+     * 3. Otherwise the turn settles `refused`.
+     */
+    async *recoverFromRefusal(input) {
+        const { recorder } = this.ctx;
+        const { response, servedBy, iterationNum } = input;
+        const refusal = response.refusal ?? {};
+        const toolCalls = response.message.toolCalls ?? [];
+        const hasPartial = (response.message.content !== null && response.message.content.length > 0) ||
+            toolCalls.length > 0;
+        this.ctx.log.warn('The model declined to answer', {
+            [NAMZU.TURN_ID]: recorder.turnId,
+            [NAMZU.ITERATION]: iterationNum,
+            'namzu.runtime.model': servedBy.model,
+            'namzu.runtime.refusal_category': refusal.category,
+            'namzu.runtime.has_partial_output': hasPartial,
+        });
+        const announce = async (outcome, fallbackModel) => {
+            await this.ctx.emitEvent({
+                type: 'model_refusal',
+                turnId: recorder.turnId,
+                iteration: iterationNum,
+                model: servedBy.model,
+                providerId: servedBy.providerId,
+                outcome,
+                ...(fallbackModel !== undefined ? { fallbackModel } : {}),
+                ...(refusal.category ? { category: refusal.category } : {}),
+                ...(refusal.explanation ? { explanation: refusal.explanation } : {}),
+            });
+        };
+        const closeIteration = async () => {
+            this.recordStep({
+                stepNumber: iterationNum,
+                model: input.stepModel,
+                servedBy,
+                messageId: input.messageId,
+                response,
+                toolResults: [],
+                toolExecutionMs: 0,
+                startedAt: input.stepStartedAt,
+                usageBefore: input.usageBefore,
+                costBefore: input.costBefore,
+            });
+            await this.ctx.emitEvent({
+                type: 'iteration_completed',
+                turnId: recorder.turnId,
+                iteration: iterationNum,
+                hasToolCalls: false,
+            });
+        };
+        if (this.ctx.abortController.signal.aborted) {
+            recorder.setStopReason('cancelled');
+            recorder.markCancelled();
+            await closeIteration();
+            yield* this.ctx.drainPending();
+            return 'settled';
+        }
+        if (!input.forceFinalize && !this.refusalFallbackUsed && this.ctx.refusalFallback !== 'off') {
+            const next = await this.refusalFallbackModel(input.stepModel, refusal);
+            if (next !== undefined) {
+                this.refusalFallbackUsed = true;
+                this.refusalPinnedModel = next;
+                await announce('fallback', next);
+                await closeIteration();
+                yield* this.ctx.drainPending();
+                return 'retry';
+            }
+        }
+        if (!input.forceFinalize && !this.refusalRetryUsed && hasPartial) {
+            this.refusalRetryUsed = true;
+            recorder.pushMessage(withStreamedMessageIdentity(createAssistantMessage(response.message.content, toolCalls.length > 0 ? toolCalls : undefined, response.message.reasoning, response.message.citations, {
+                type: 'model',
+                ...servedBy,
+                ...(response.message.replayState !== undefined
+                    ? { replayState: response.message.replayState }
+                    : {}),
+            }, response.message.textParts), input.messageId));
+            for (const call of toolCalls) {
+                recorder.pushMessage(createToolMessage(REFUSED_REPLY_CALL_RESULT, call.id, true));
+            }
+            recorder.pushMessage(createRuntimeContextMessage(REFUSED_REPLY_RETRY_MESSAGE, 'refusal-retry'));
+            await announce('retry');
+            await closeIteration();
+            yield* this.ctx.drainPending();
+            return 'retry';
+        }
+        recorder.setLastError(`${servedBy.model} declined to answer this message${refusal.explanation ? `: ${refusal.explanation}` : '.'}`);
+        // A closing step that a limit asked for keeps that limit as the reason
+        // the turn ended; the refusal is still announced.
+        recorder.setStopReason(input.limitStopReason ?? 'refused');
+        await announce('declined');
+        await closeIteration();
+        yield* this.ctx.drainPending();
+        return 'settled';
+    }
+    /**
+     * Another model to try after `model` declined, or `undefined` when there is
+     * none. Only the provider can say: it names its own recommendation or its
+     * own declared order, checked against what this credential can serve. A
+     * chain member declared with a model of its own cannot be swapped, because
+     * the chain would put its own model back on the request.
+     */
+    async refusalFallbackModel(model, refusal) {
+        if (this.ctx.servingMember?.()?.model !== undefined)
+            return undefined;
+        const pick = this.ctx.provider.refusalFallbackFor;
+        if (!pick)
+            return undefined;
+        try {
+            const next = await pick.call(this.ctx.provider, model, refusal, this.ctx.abortController.signal);
+            return next !== undefined && next.length > 0 && next !== model ? next : undefined;
+        }
+        catch (err) {
+            this.ctx.log.warn('The provider could not name a model to retry a refusal on', {
+                'exception.message': toErrorMessage(err),
+            });
+            return undefined;
+        }
+    }
     async requestFinalResponse(model, reason) {
         if (this.ctx.structuredOutput?.mode === 'native')
             return 'structured_output_failed';
@@ -2537,6 +2721,15 @@ export class IterationOrchestrator {
                 providerId: servedBy.providerId,
                 model: servedBy.model,
             });
+            // A closing request the provider declined has nothing to add, and its
+            // empty reply must not be stored or sent again.
+            if (response.finishReason === 'content_filter') {
+                this.ctx.log.warn('The closing response was declined by the model', {
+                    [NAMZU.TURN_ID]: this.ctx.recorder.turnId,
+                    'namzu.runtime.model': servedBy.model,
+                });
+                return undefined;
+            }
             const finalMessageId = generateMessageId();
             const assistantMsg = withStreamedMessageIdentity(createAssistantMessage(response.message.content, undefined, response.message.reasoning, response.message.citations, {
                 type: 'model',