@namzu/sdk 60.0.0 → 60.2.0

package/src/manager/session/turn-recorder.ts

@@ -12,6 +12,7 @@ import {
 	type SessionLog,
 	type SessionLogEntry,
 	type SessionLogHead,
+	type SessionLogWriteHealth,
 	SessionMessageFold,
 	withMessageId,
 } from '../../store/session-log/index.js'
@@ -130,6 +131,7 @@ const TURN_BOUND_EVENT_TYPES: ReadonlySet<SessionEventType> = new Set<SessionEve
 	'hosted_tool',
 	'provider_retry',
 	'provider_fallback',
+	'model_refusal',
 	'tool_completed',
 	'user_question_asked',
 	'user_question_answered',
@@ -650,6 +652,9 @@ export class TurnRecorder {
 				this.#leaseHeartbeat = setInterval(() => this.#queueLeaseRenewal(), this.#leaseTtlMs / 2)
 				this.#leaseHeartbeat.unref()
 			}
+			this.#stopWatchingHealth ??= this.log.onWriteHealth?.((change) => {
+				for (const listener of this.#healthListeners) listener(change)
+			})
 			const head = await this.log.head()
 			if (head === null) {
 				this.#lastEntry = await this.log.append(lease, {
@@ -680,6 +685,21 @@ export class TurnRecorder {
 		}
 	}
 
+	/**
+	 * Be told when the session log stops writing (the disk is full) and when
+	 * it writes again. Sent while the recorder holds the log, from `open` to
+	 * `release`.
+	 */
+	onLogWriteHealth(listener: (change: SessionLogWriteHealth) => void): () => void {
+		this.#healthListeners.add(listener)
+		return () => {
+			this.#healthListeners.delete(listener)
+		}
+	}
+
+	readonly #healthListeners = new Set<(change: SessionLogWriteHealth) => void>()
+	#stopWatchingHealth: (() => void) | undefined
+
 	/** Serialize timer and write-triggered renewals so release uses the latest token. */
 	#queueLeaseRenewal(): void {
 		this.#leaseRenewal = this.#leaseRenewal
@@ -724,6 +744,8 @@ export class TurnRecorder {
 
 	/** Give up a lease the recorder claimed. Never throws. */
 	async release(): Promise<void> {
+		this.#stopWatchingHealth?.()
+		this.#stopWatchingHealth = undefined
 		if (!this.#ownsLease || !this.#lease) return
 		this.#released = true
 		if (this.#leaseHeartbeat !== undefined) clearInterval(this.#leaseHeartbeat)

package/src/peers/dir.ts

@@ -123,6 +123,9 @@ function peerRuntimeDirCandidates(options: ResolvePeerRuntimeDirOptions): readon
 	const candidates: string[] = []
 	if (options.env.XDG_RUNTIME_DIR) candidates.push(join(options.env.XDG_RUNTIME_DIR, 'namzu'))
 	candidates.push(join(options.namzuHome, 'run'))
+	// The operating system's own temporary directory, not `NAMZU_TMPDIR`: this
+	// is the last resort for a socket path, and a relocated base is usually a
+	// long path that would not fit the platform's socket-path limit.
 	candidates.push(join(options.tmpDir ?? tmpdir(), `namzu-${options.uid ?? 'user'}`))
 	return candidates
 }

package/src/provider/collect-chat-completion.ts

@@ -72,6 +72,7 @@ export async function collectChatCompletion(
 	let replayState: unknown
 	let finishReason: ChatCompletionResponse['finishReason'] = 'stop'
 	let finishDetail: ChatCompletionResponse['finishDetail']
+	let refusal: ChatCompletionResponse['refusal']
 	let usage: ChatCompletionResponse['usage'] = {
 		promptTokens: 0,
 		completionTokens: 0,
@@ -158,6 +159,7 @@ export async function collectChatCompletion(
 			finishReason = chunk.finishReason
 			finishDetail = chunk.finishReason === 'length' ? chunk.finishDetail : undefined
 		}
+		if (chunk.refusal) refusal = chunk.refusal
 		// Merge (per-field max), not last-write-wins: a late frame that omits
 		// input/cache tokens must not zero the counts captured earlier in the stream.
 		if (chunk.usage) usage = mergeTokenUsage(usage, chunk.usage)
@@ -207,6 +209,7 @@ export async function collectChatCompletion(
 		},
 		finishReason,
 		...(finishDetail ? { finishDetail } : {}),
+		...(refusal && finishReason === 'content_filter' ? { refusal } : {}),
 		usage,
 	}
 }

package/src/provider/fallback.ts

@@ -572,6 +572,23 @@ export function withProviderFallback(
 					) => first.provider.effortLevelsFor?.(model, thinking) ?? [],
 				}
 			: {}),
+		// Answered by the member the next request goes to first, the one the
+		// cursor rests on: it is the member whose model just declined.
+		...(members.some((member) => member.provider.refusalFallbackFor)
+			? {
+					refusalFallbackFor: (
+						model: string,
+						refusal: Parameters<NonNullable<LLMProvider['refusalFallbackFor']>>[1],
+						signal?: AbortSignal,
+					) => {
+						const serving = members[cursor] ?? first
+						return (
+							serving.provider.refusalFallbackFor?.(serving.model ?? model, refusal, signal) ??
+							Promise.resolve(undefined)
+						)
+					},
+				}
+			: {}),
 		...(first.provider.resolveContextWindow
 			? {
 					resolveContextWindow: (model: string, signal?: AbortSignal) =>

package/src/provider/idle-timeout.ts

@@ -247,6 +247,15 @@ export function withStreamIdleTimeout(
 					) => provider.effortLevelsFor?.(model, thinking) ?? [],
 				}
 			: {}),
+		...(provider.refusalFallbackFor
+			? {
+					refusalFallbackFor: (
+						model: string,
+						refusal: Parameters<NonNullable<LLMProvider['refusalFallbackFor']>>[1],
+						signal?: AbortSignal,
+					) => provider.refusalFallbackFor?.(model, refusal, signal) ?? Promise.resolve(undefined),
+				}
+			: {}),
 		...(provider.resolveContextWindow
 			? {
 					resolveContextWindow: (model: string, signal?: AbortSignal) =>

package/src/provider/mock.ts

@@ -49,11 +49,19 @@ export class MockLLMProvider implements LLMProvider {
 	/** Every request this provider has received, in order. */
 	readonly requests: ChatCompletionParams[] = []
 
+	/** Present only when the script names a model to retry a refusal on. */
+	readonly refusalFallbackFor?: (model: string) => Promise<string | undefined>
+
 	constructor(config: MockScript = {}) {
 		this.capabilities = config.capabilities
 		this.model = config.model ?? FALLBACK_MOCK_MODEL
 		this.responseDelayMs = config.responseDelayMs ?? 0
 		this.onRequest = config.onRequest
+		const refusalFallbackModel = config.refusalFallbackModel
+		if (refusalFallbackModel !== undefined) {
+			this.refusalFallbackFor = async (model) =>
+				model === refusalFallbackModel ? undefined : refusalFallbackModel
+		}
 		this.nextTurn = config.nextTurn
 		this.turns = config.turns ?? [{ text: config.responseText ?? 'Mock provider response' }] // Back-compat: the old single-string config becomes a one-turn script.
 	}
@@ -158,18 +166,20 @@ export class MockLLMProvider implements LLMProvider {
 			yield { id, delta: { toolCallEnd: { index, id: callId } } }
 		}
 
+		const finishReason: NonNullable<StreamChunk['finishReason']> =
+			turn.finishReason ??
+			// A call cut off mid-JSON is what the output limit does, and the
+			// finish reason is how a consumer tells that from malformed JSON.
+			(toolCalls.some((call) => call.truncateArguments === true)
+				? 'length'
+				: toolCalls.length > 0
+					? 'tool_calls'
+					: 'stop')
 		yield {
 			id,
 			delta: {},
-			finishReason:
-				turn.finishReason ??
-				// A call cut off mid-JSON is what the output limit does, and the
-				// finish reason is how a consumer tells that from malformed JSON.
-				(toolCalls.some((call) => call.truncateArguments === true)
-					? 'length'
-					: toolCalls.length > 0
-						? 'tool_calls'
-						: 'stop'),
+			finishReason,
+			...(finishReason === 'content_filter' ? { refusal: turn.refusal ?? {} } : {}),
 			usage: { ...EMPTY_USAGE, ...turn.usage },
 		}
 	}

package/src/provider/model-window-suffix.ts

@@ -20,6 +20,7 @@ const MODEL_FIRST_METHODS: ReadonlySet<string> = new Set([
 	'reasoningEffortDefaultFor',
 	'effortLevelsFor',
 	'resolveContextWindow',
+	'refusalFallbackFor',
 	'healthCheck',
 	'doctorCheck',
 ])

package/src/provider/retry.ts

@@ -417,6 +417,15 @@ export function withProviderRetry(
 					) => provider.effortLevelsFor?.(model, thinking) ?? [],
 				}
 			: {}),
+		...(provider.refusalFallbackFor
+			? {
+					refusalFallbackFor: (
+						model: string,
+						refusal: Parameters<NonNullable<LLMProvider['refusalFallbackFor']>>[1],
+						signal?: AbortSignal,
+					) => provider.refusalFallbackFor?.(model, refusal, signal) ?? Promise.resolve(undefined),
+				}
+			: {}),
 		...(provider.resolveContextWindow
 			? {
 					resolveContextWindow: (model: string, signal?: AbortSignal) =>

package/src/public-runtime.ts

@@ -291,6 +291,19 @@ export {
 } from './utils/shell-compress.js'
 export { createChildAbortController } from './utils/abort.js'
 export { memoizeAsync } from './utils/memoize.js'
+export {
+	NAMZU_TMPDIR_ENV,
+	type PrivateTempRootOptions,
+	TempDirectoryError,
+	type TempDirectoryFailure,
+	createTempDir,
+	createTempDirSync,
+	ensureScratchpadDirectory,
+	privateTempRoot,
+	privateTempRootPath,
+	resolveTempBase,
+	tempFilePath,
+} from './utils/temp.js'
 export { extractFinalResponse } from './utils/conversation.js'
 
 // ─── router, runtime, turn ───────────────────────────────────────────────

package/src/runtime/query/events.ts

@@ -79,6 +79,25 @@ export class EventTranslator {
 		this.recorder = recorder
 		this.probes = probeRegistry
 		this.log = resolveLogger(log).child({ [SCOPE_ATTRIBUTE]: 'runtime/query/events' })
+		recorder.onLogWriteHealth((change) => {
+			// Live only: the log is what cannot be written. The listener runs inside
+			// a log write, so it must not wait on one.
+			void this.emitEvent(
+				change.state === 'degraded'
+					? {
+							type: 'session_log_degraded',
+							cause: change.cause,
+							bufferedRecords: change.bufferedRecords,
+							bufferedBytes: change.bufferedBytes,
+							...(change.dropping ? { dropping: true } : {}),
+						}
+					: {
+							type: 'session_log_recovered',
+							flushedRecords: change.flushedRecords,
+							droppedRecords: change.droppedRecords,
+						},
+			)
+		})
 	}
 
 	/** Serializes appends and reads against each other. */

package/src/runtime/query/executor.ts

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto'
-import { join, resolve } from 'node:path'
+import { isAbsolute, join, resolve } from 'node:path'
 import type { Span } from '@opentelemetry/api'
 import type { AuthorizationGate } from '../../authorization/gate.js'
 import { unknownProgramInLine } from '../../authorization/program.js'
@@ -24,7 +24,7 @@ import { fingerprintContent } from '../../tools/builtins/content-fingerprint.js'
 import { sandboxShellSpawn, withoutBashStartup } from '../../tools/command-shell.js'
 import { isAlwaysDestructive } from '../../tools/defineTool.js'
 import { createFileReadTracker } from '../../tools/file-read-tracker.js'
-import { pathOutsideRoots, toolRoots } from '../../tools/paths.js'
+import { pathOutsideRoots, resolveWithinAnyReal, toolRoots } from '../../tools/paths.js'
 import { resolveRetainedOutput } from '../../tools/retained-output.js'
 import type { ToolManager } from '../../toolsets/manager.js'
 import type { ToolSourceRef } from '../../toolsets/types.js'
@@ -70,6 +70,7 @@ import { generateToolCallId } from '../../utils/id.js'
 import type { Logger } from '../../utils/logger.js'
 import { compressShellOutput } from '../../utils/shell-compress.js'
 import { parseStructuredResultJson } from '../../utils/structured-result-json.js'
+import { ensureScratchpadDirectory } from '../../utils/temp.js'
 import { type BackgroundJobRegistry, type JobProcess, bindOwner } from '../jobs/registry.js'
 import { type BatchDetach, stillRunningResult } from './detached-calls.js'
 import {
@@ -155,12 +156,15 @@ export interface PreparedToolBatch {
 		readonly escalation?: ToolCallEscalation
 		/** What a `pre_tool_use` hook asked for this call's approval; see `ToolCallSummary.hookPermission`. */
 		readonly hookPermission?: PluginHookPermission
+		/** The call writes inside the session's scratch folder; see `ToolCallSummary.scratchpadWrite`. */
+		readonly scratchpadWrite?: true
 	}[]
 }
 
 interface OwnedPreparedToolBatch extends PreparedToolBatch {
 	readonly calls: ReadonlyMap<string, PreparedDirectCall>
 	readonly escalations: ReadonlyMap<string, ToolCallEscalation>
+	readonly scratchpadWrites: ReadonlySet<string>
 }
 
 /**
@@ -363,6 +367,13 @@ export interface ToolExecutorConfig {
 	workingDirectory: string
 	/** See `ToolContext.additionalDirectories`. */
 	additionalDirectories?: readonly string[]
+	/**
+	 * Where this session's own scratch folder is (it need not exist). It becomes
+	 * a root of the file tools, and a write inside it needs no review, once a call
+	 * names it and the folder has been made and checked. Unset on a sandboxed
+	 * turn and on a session with no layout on disk.
+	 */
+	scratchpadDirectory?: string
 	/** See `QueryParams.outsideRootAccess`. Default `'refuse'`. */
 	outsideRootAccess?: 'refuse' | 'review'
 	/** See `QueryParams.sandboxEscape`. Default `'refuse'`. */
@@ -814,6 +825,68 @@ export class ToolExecutor {
 	}
 
 	/** True once the turn has a sandbox, or is certain to get one before a tool runs. */
+	/** The scratch folder, once a call has named it and it has been made and checked. */
+	private scratchpadReady: string | undefined
+
+	/** The tools' roots now: the turn's, plus the scratch folder once it is ready. */
+	private rootsNow(): readonly string[] {
+		return toolRoots({
+			workingDirectory: this.config.workingDirectory,
+			additionalDirectories: this.additionalDirectoriesNow(),
+		})
+	}
+
+	private additionalDirectoriesNow(): readonly string[] | undefined {
+		if (this.scratchpadReady === undefined) return this.config.additionalDirectories
+		return [...(this.config.additionalDirectories ?? []), this.scratchpadReady]
+	}
+
+	/**
+	 * Make the session's scratch folder a root when a call names it. Lazy: a
+	 * session that never uses it leaves nothing on disk. The folder must be
+	 * inside the private temporary root with no link on the way; otherwise it
+	 * stays outside the roots and a path in it is asked about like any other.
+	 */
+	private admitScratchpad(call: PreparedSafetyCall): void {
+		const directory = this.config.scratchpadDirectory
+		if (directory === undefined || this.scratchpadReady !== undefined || this.sandboxed) return
+		if (call.kind === 'synthetic') return
+		let named = false
+		try {
+			named = JSON.stringify(call.input)?.includes(JSON.stringify(directory).slice(1, -1)) === true
+		} catch {
+			// An input that cannot be serialised names nothing.
+		}
+		if (!named) return
+		try {
+			this.scratchpadReady = ensureScratchpadDirectory(directory)
+		} catch (error) {
+			this.log.warn('The session scratch folder could not be made, so it stays outside the roots', {
+				'exception.message': error instanceof Error ? error.message : String(error),
+			})
+		}
+	}
+
+	/** Whether `call` writes a file inside the ready scratch folder and nothing else about it is notable. */
+	private async writesScratchpad(
+		call: PreparedSafetyCall,
+		escalation: ToolCallEscalation | undefined,
+	): Promise<boolean> {
+		const root = this.scratchpadReady
+		if (root === undefined || escalation !== undefined || call.kind === 'synthetic') return false
+		if (call.toolName !== 'write' && call.toolName !== 'edit') return false
+		const tool = this.config.tools.get(call.toolName)
+		if (!tool?.pathArgument || call.input === null || typeof call.input !== 'object') return false
+		const value = (call.input as Record<string, unknown>)[tool.pathArgument]
+		if (typeof value !== 'string' || !isAbsolute(value)) return false
+		try {
+			await resolveWithinAnyReal([root], value)
+			return true
+		} catch {
+			return false
+		}
+	}
+
 	private get sandboxed(): boolean {
 		return this.config.sandbox !== undefined || this.sandboxGate !== undefined
 	}
@@ -1126,6 +1199,7 @@ export class ToolExecutor {
 		if ((response.message.toolCalls ?? []).length > 0) await this.awaitSandbox()
 		const calls = new Map<string, PreparedDirectCall>()
 		const escalations = new Map<string, ToolCallEscalation>()
+		const scratchpadWrites = new Set<string>()
 		const earlierPaths: string[] = []
 		for (const toolCall of response.message.toolCalls ?? []) {
 			const prepared = await prepareDirectCall(
@@ -1137,11 +1211,13 @@ export class ToolExecutor {
 			const path = inputPathOf(prepared)
 			if (path !== undefined) earlierPaths.push(path)
 			calls.set(toolCall.id, call)
+			this.admitScratchpad(call)
 			const escalation = await this.escalationOrUnfinished(call)
 			if (escalation) escalations.set(toolCall.id, escalation)
+			if (await this.writesScratchpad(call, escalation)) scratchpadWrites.add(toolCall.id)
 		}
 		this.config.abortSignal.throwIfAborted()
-		return this.publishPreparedBatch(calls, escalations)
+		return this.publishPreparedBatch(calls, escalations, scratchpadWrites)
 	}
 
 	/**
@@ -1250,7 +1326,7 @@ export class ToolExecutor {
 				// result that was cut told the model to look.
 				const retained =
 					tool.name === 'read' && (await resolveRetainedOutput(this.outputDirectory(), value))
-				const outside = retained ? undefined : await pathOutsideRoots(toolRoots(this.config), value)
+				const outside = retained ? undefined : await pathOutsideRoots(this.rootsNow(), value)
 				if (outside !== undefined) outsidePaths = [outside]
 			}
 		}
@@ -1307,7 +1383,7 @@ export class ToolExecutor {
 		protectedPaths: readonly string[]
 		dangerousRemoval?: string
 	}> {
-		const roots = toolRoots(this.config)
+		const roots = this.rootsNow()
 		const protectedPaths: string[] = []
 		let outsidePaths: readonly string[] = []
 		let removal: string | undefined
@@ -1376,6 +1452,7 @@ export class ToolExecutor {
 		}
 		const calls = new Map((previous as OwnedPreparedToolBatch).calls)
 		const escalations = new Map((previous as OwnedPreparedToolBatch).escalations)
+		const scratchpadWrites = new Set((previous as OwnedPreparedToolBatch).scratchpadWrites)
 		const earlierPaths: string[] = []
 		for (const toolCall of response.message.toolCalls ?? []) {
 			if (changedCallIds.has(toolCall.id)) {
@@ -1384,21 +1461,25 @@ export class ToolExecutor {
 					earlierPaths,
 				)
 				calls.set(toolCall.id, call)
+				this.admitScratchpad(call)
 				const escalation = await this.escalationOrUnfinished(call)
 				if (escalation) escalations.set(toolCall.id, escalation)
 				else escalations.delete(toolCall.id)
+				if (await this.writesScratchpad(call, escalation)) scratchpadWrites.add(toolCall.id)
+				else scratchpadWrites.delete(toolCall.id)
 			}
 			const prepared = calls.get(toolCall.id)
 			const path = prepared ? inputPathOf(prepared) : undefined
 			if (path !== undefined) earlierPaths.push(path)
 		}
 		this.config.abortSignal.throwIfAborted()
-		return this.publishPreparedBatch(calls, escalations)
+		return this.publishPreparedBatch(calls, escalations, scratchpadWrites)
 	}
 
 	private publishPreparedBatch(
 		calls: ReadonlyMap<string, PreparedDirectCall>,
 		escalations: ReadonlyMap<string, ToolCallEscalation>,
+		scratchpadWrites: ReadonlySet<string>,
 	): PreparedToolBatch {
 		const reviewCalls = [...calls.values()]
 			.filter(
@@ -1414,12 +1495,14 @@ export class ToolExecutor {
 					input: call.input,
 					...(escalation ? { escalation } : {}),
 					...(hookPermission ? { hookPermission } : {}),
+					...(scratchpadWrites.has(call.toolCall.id) ? { scratchpadWrite: true as const } : {}),
 				}
 			})
 		const batch: OwnedPreparedToolBatch = Object.freeze({
 			reviewCalls: Object.freeze(reviewCalls),
 			calls: new Map(calls),
 			escalations: new Map(escalations),
+			scratchpadWrites: new Set(scratchpadWrites),
 		})
 		this.preparedBatches.add(batch)
 		return batch
@@ -2032,6 +2115,7 @@ export class ToolExecutor {
 		} catch {
 			needsApproval = true
 		}
+		this.admitScratchpad(preparedCall)
 		const nestedEscalation = await this.escalationOrUnfinished(preparedCall)
 		if (nestedEscalation || needsApproval || (gateResult && gateResult.decision !== 'allow')) {
 			const reason = nestedEscalation
@@ -2276,8 +2360,8 @@ export class ToolExecutor {
 			sessionId: this.config.sessionId,
 			turnId: this.config.turnId,
 			workingDirectory: this.config.workingDirectory,
-			...(this.config.additionalDirectories?.length
-				? { additionalDirectories: this.config.additionalDirectories }
+			...(this.additionalDirectoriesNow()?.length
+				? { additionalDirectories: this.additionalDirectoriesNow() }
 				: {}),
 			...(this.config.authorizationGate
 				? {

package/src/runtime/query/index.ts

@@ -377,6 +377,20 @@ export interface QueryParams {
 	 * before; `0` stops at the first cut-off.
 	 */
 	maxOutputContinuations?: number
+	/**
+	 * What the turn does when the model declines to answer (its provider
+	 * finished the reply as a refusal or a safety block).
+	 *
+	 * `'auto'` (the default) re-runs the refused request once on another model
+	 * of the same provider (the one the provider recommends, or the one its
+	 * own fallback order names) and keeps that model for the rest of the turn;
+	 * a `model_refusal` event names the swap so a host can keep it for later
+	 * turns. `'off'` never changes the model: the turn tries once more on the
+	 * same model only when the refused reply had partial output, and otherwise
+	 * settles with stop reason `'refused'`. A refused reply is never added to
+	 * the history sent next.
+	 */
+	refusalFallback?: 'auto' | 'off'
 
 	/**
 	 * Model-visible size cap for a single tool result. Over-budget output is
@@ -1528,6 +1542,17 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 		// pre-approves ends with the turn. Shared by the executor, where the
 		// `skill` tool records a grant, and the review phase, which reads it.
 		const skillGrants = new SkillGrantSet()
+		// The session's own scratch folder, a root of the file tools once a call
+		// names it. Not for a sandboxed turn (it is not mounted there), and not
+		// for a session whose state is not on disk.
+		let scratchpadDirectory: string | undefined
+		if (!params.sandboxProvider) {
+			try {
+				scratchpadDirectory = ctx.storage.paths?.scratchpadPath(ctx.sessionId)
+			} catch {
+				scratchpadDirectory = undefined
+			}
+		}
 		const toolExecutor = ToolingBootstrap.init(
 			{
 				skillGrants,
@@ -1541,6 +1566,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 				...(params.additionalDirectories?.length
 					? { additionalDirectories: params.additionalDirectories }
 					: {}),
+				...(scratchpadDirectory ? { scratchpadDirectory } : {}),
 				...(params.outsideRootAccess ? { outsideRootAccess: params.outsideRootAccess } : {}),
 				...(params.sandboxEscape ? { sandboxEscape: params.sandboxEscape } : {}),
 				permissionMode: () => ctx.permissionMode.current,
@@ -1883,6 +1909,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			...(params.maxOutputContinuations !== undefined
 				? { maxOutputContinuations: params.maxOutputContinuations }
 				: {}),
+			...(params.refusalFallback !== undefined ? { refusalFallback: params.refusalFallback } : {}),
 			...(params.inboundMessages ? { inboundMessages: params.inboundMessages } : {}),
 			...(params.reminders ? { reminders: params.reminders } : {}),
 			...(params.durableInbound ? { durableInbound: params.durableInbound } : {}),

package/src/runtime/query/iteration/effort-clamp.ts

@@ -0,0 +1,46 @@
+import type { LLMProvider, ReasoningEffort, ThinkingConfig } from '../../../types/provider/index.js'
+
+/** Lowest to highest, the order the effort menus are drawn in. */
+const EFFORT_ORDER: readonly ReasoningEffort[] = [
+	'none',
+	'minimal',
+	'low',
+	'medium',
+	'high',
+	'xhigh',
+	'max',
+	'ultra',
+]
+
+/**
+ * The effort to send to `model` when the turn was configured for another one.
+ *
+ * A level the model does not offer is rejected by some drivers, so a request
+ * moved to a different model (a refusal fallback, a live model pick) carries
+ * the nearest level that model supports: the next one down when there is one,
+ * otherwise the lowest one above. The menu comes from the provider, never from
+ * a copy here. A provider that cannot say what the model offers, or a level
+ * the model already offers, leaves the effort exactly as configured.
+ */
+export function effortForModel(
+	provider: LLMProvider,
+	model: string,
+	effort: ReasoningEffort,
+	thinking?: ThinkingConfig,
+): ReasoningEffort {
+	let menu: readonly ReasoningEffort[] | undefined
+	try {
+		menu = provider.reasoningEffortLevelsFor
+			? provider.reasoningEffortLevelsFor(model, thinking)
+			: provider.effortLevelsFor?.(model, thinking)
+	} catch {
+		return effort
+	}
+	if (!menu || menu.length === 0 || menu.includes(effort)) return effort
+	const rank = (level: ReasoningEffort) => EFFORT_ORDER.indexOf(level)
+	const wanted = rank(effort)
+	if (wanted < 0) return effort
+	const ranked = menu.filter((level) => rank(level) >= 0).sort((a, b) => rank(a) - rank(b))
+	const below = ranked.filter((level) => rank(level) < wanted)
+	return below[below.length - 1] ?? ranked[0] ?? effort
+}