@namzu/sdk 52.0.0 → 52.1.0

package/src/runtime/query/iteration/stream-turn.ts

@@ -42,7 +42,11 @@ import { generateMessageId, generateToolCallId } from '../../../utils/id.js'
 import type { Logger } from '../../../utils/logger.js'
 import type { EmitEvent } from '../events.js'
 import type { RequestImageIdentity } from '../request-rich-content.js'
-import { streamWithProviderRejectedImageRecovery } from './provider-rejected-image.js'
+import {
+	type TextOnlyModelRecovery,
+	streamWithProviderRejectedImageRecovery,
+} from './provider-rejected-image.js'
+import type { RequestRepair } from './request-repair.js'
 import {
 	type ParsedToolArguments,
 	capPartialArguments,
@@ -237,6 +241,10 @@ export async function* streamProviderTurn(
 	announceAs?: import('../../../types/ids/index.js').MessageId,
 	imageRecovery?: {
 		readonly onAccepted: (identity: RequestImageIdentity) => Promise<void>
+		/** A model refused the request for holding an image it cannot read; the retry sent none. */
+		readonly textOnly?: TextOnlyModelRecovery
+		/** Repairs and resends a request the provider rejects as invalid. */
+		readonly repair?: RequestRepair
 	},
 	captureRequest = false,
 	/** The session the turn belongs to, named on the chat span as `gen_ai.conversation.id`. */
@@ -363,6 +371,8 @@ export async function* streamProviderTurn(
 					streamParams,
 					imageRecovery.onAccepted,
 					observeRequest,
+					imageRecovery.textOnly,
+					imageRecovery.repair,
 				)
 			: provider.chatStream(streamParams)
 	) as AsyncIterable<StreamChunk>

package/src/runtime/query/request-rich-content.ts

@@ -34,7 +34,8 @@ interface RichOccurrence {
 	readonly source: 'user' | 'tool'
 	readonly kind: RichKind
 	readonly bytes: number
-	readonly reason: 'budget' | 'provider-rejected' | 'invalid-image'
+	readonly mediaType?: string
+	readonly reason: 'budget' | 'provider-rejected' | 'invalid-image' | 'model-text-only'
 }
 
 export interface RequestImageIdentity {
@@ -65,6 +66,24 @@ const invalidUserImageMarker = (): string =>
 const invalidToolImageMarker = (): string =>
 	`[image omitted from this model request because the producing tool returned encoded bytes that are not a complete supported raster matching the declared media type. ${toolRecovery} Correct the image source before presenting it again.]`
 
+/** `12 KB`-style size of an encoded payload, so the model can tell a thumbnail from a full screenshot. */
+function describeEncodedSize(base64Length: number): string {
+	const bytes = Math.floor((base64Length * 3) / 4)
+	if (bytes < 1024) return `${bytes} B`
+	if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`
+	return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+}
+
+/**
+ * What stands in for an image the current model cannot read. It says so, and
+ * what the image was, because the model otherwise sees a tool that reported
+ * success next to nothing and tends to retry it or claim to have seen the screen.
+ */
+const textOnlyImageMarker = (mediaType: string | undefined, base64Length: number): string =>
+	`[image omitted: the current model cannot read images${
+		mediaType ? ` (${mediaType}, ${describeEncodedSize(base64Length)})` : ''
+	}]`
+
 function assertInlineAttachment(
 	attachment: MessageAttachment,
 ): asserts attachment is Exclude<MessageAttachment, { readonly type: 'stored' }> {
@@ -75,7 +94,10 @@ function assertInlineAttachment(
 	}
 }
 
-function collectRichOccurrences(messages: readonly Message[]): RichOccurrence[] {
+function collectRichOccurrences(
+	messages: readonly Message[],
+	imagesReadable: boolean,
+): RichOccurrence[] {
 	const occurrences: RichOccurrence[] = []
 
 	for (const [messageIndex, message] of messages.entries()) {
@@ -88,13 +110,17 @@ function collectRichOccurrences(messages: readonly Message[]): RichOccurrence[]
 					source: 'user',
 					kind: attachment.type === 'document' ? 'document' : 'image',
 					bytes: attachment.data.length,
+					mediaType: attachment.mediaType,
 					reason:
-						attachment.type !== 'document' && attachment.modelOmission?.reason === 'invalid-image'
-							? 'invalid-image'
+						attachment.type !== 'document' && !imagesReadable
+							? 'model-text-only'
 							: attachment.type !== 'document' &&
-									attachment.modelOmission?.reason === 'provider-rejected'
-								? 'provider-rejected'
-								: 'budget',
+									attachment.modelOmission?.reason === 'invalid-image'
+								? 'invalid-image'
+								: attachment.type !== 'document' &&
+										attachment.modelOmission?.reason === 'provider-rejected'
+									? 'provider-rejected'
+									: 'budget',
 				})
 			}
 			continue
@@ -109,12 +135,15 @@ function collectRichOccurrences(messages: readonly Message[]): RichOccurrence[]
 				source: 'tool',
 				kind: block.type,
 				bytes: block.data.length,
+				mediaType: block.mediaType,
 				reason:
-					block.type === 'image' && block.modelOmission?.reason === 'invalid-image'
-						? 'invalid-image'
-						: block.type === 'image' && block.modelOmission?.reason === 'provider-rejected'
-							? 'provider-rejected'
-							: 'budget',
+					block.type === 'image' && !imagesReadable
+						? 'model-text-only'
+						: block.type === 'image' && block.modelOmission?.reason === 'invalid-image'
+							? 'invalid-image'
+							: block.type === 'image' && block.modelOmission?.reason === 'provider-rejected'
+								? 'provider-rejected'
+								: 'budget',
 			})
 		}
 	}
@@ -130,11 +159,13 @@ function appendTextMarkers(content: string, markers: readonly string[]): string
 
 function appendMarkers(content: string, occurrences: readonly RichOccurrence[]): string {
 	const markers = occurrences.map((occurrence) =>
-		occurrence.reason === 'provider-rejected'
-			? rejectedUserImageMarker()
-			: occurrence.reason === 'invalid-image'
-				? invalidUserImageMarker()
-				: userMarker(occurrence.kind),
+		occurrence.reason === 'model-text-only'
+			? textOnlyImageMarker(occurrence.mediaType, occurrence.bytes)
+			: occurrence.reason === 'provider-rejected'
+				? rejectedUserImageMarker()
+				: occurrence.reason === 'invalid-image'
+					? invalidUserImageMarker()
+					: userMarker(occurrence.kind),
 	)
 	return appendTextMarkers(content, markers)
 }
@@ -148,8 +179,12 @@ function appendMarkers(content: string, occurrences: readonly RichOccurrence[]):
  * original array when nothing is omitted makes the no-op and exact-boundary
  * cases observable and keeps the common path allocation-free.
  */
-export function projectRequestRichContent(messages: Message[], maxBytes: number): Message[] {
-	const occurrences = collectRichOccurrences(messages)
+export function projectRequestRichContent(
+	messages: Message[],
+	maxBytes: number,
+	options: { readonly imagesReadable?: boolean } = {},
+): Message[] {
+	const occurrences = collectRichOccurrences(messages, options.imagesReadable ?? true)
 	if (occurrences.length === 0) return messages
 
 	const omitted = new Map<number, Map<number, RichOccurrence>>()
@@ -163,9 +198,7 @@ export function projectRequestRichContent(messages: Message[], maxBytes: number)
 	}
 
 	for (const occurrence of occurrences) {
-		if (occurrence.reason === 'provider-rejected' || occurrence.reason === 'invalid-image') {
-			omit(occurrence)
-		}
+		if (occurrence.reason !== 'budget') omit(occurrence)
 	}
 
 	let total = occurrences.reduce(
@@ -206,11 +239,13 @@ export function projectRequestRichContent(messages: Message[], maxBytes: number)
 					? {
 							type: 'text',
 							text:
-								occurrence.reason === 'provider-rejected'
-									? rejectedToolImageMarker()
-									: occurrence.reason === 'invalid-image'
-										? invalidToolImageMarker()
-										: toolMarker(occurrence.kind),
+								occurrence.reason === 'model-text-only'
+									? textOnlyImageMarker(occurrence.mediaType, occurrence.bytes)
+									: occurrence.reason === 'provider-rejected'
+										? rejectedToolImageMarker()
+										: occurrence.reason === 'invalid-image'
+											? invalidToolImageMarker()
+											: toolMarker(occurrence.kind),
 						}
 					: block
 			})
@@ -221,6 +256,21 @@ export function projectRequestRichContent(messages: Message[], maxBytes: number)
 	})
 }
 
+/** Whether the provider-bound request carries an image anywhere, in a user attachment or a tool result. */
+export function requestHasImages(messages: readonly Message[]): boolean {
+	for (const message of messages) {
+		if (message.role === 'user') {
+			for (const attachment of message.attachments ?? []) {
+				if (attachment.type !== 'stored' && attachment.type !== 'document') return true
+			}
+			continue
+		}
+		if (message.role !== 'tool' || !Array.isArray(message.content)) continue
+		if (message.content.some((block) => block.type === 'image')) return true
+	}
+	return false
+}
+
 function sameImage(
 	image: { readonly data: string; readonly mediaType: string },
 	identity: RequestImageIdentity,

package/src/tools/builtins/computer-use.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod'
-import { resolveProviderCapabilities } from '../../provider/capabilities.js'
+import { modelReadsImages, resolveProviderCapabilities } from '../../provider/capabilities.js'
 import type {
 	ComputerUseAction,
 	ComputerUseCapabilities,
@@ -105,10 +105,19 @@ export interface ComputerUseToolOptions {
  * {@link ComputerUseToolOptions.unavailableReason}.
  */
 export function computerUseUnavailableReason(
-	provider: Pick<LLMProvider, 'id' | 'capabilities'>,
+	provider: Pick<LLMProvider, 'id' | 'capabilities' | 'supportsImageInputFor'>,
+	model?: string,
 ): string | undefined {
-	if (resolveProviderCapabilities(provider).supportsToolResultImages) return undefined
-	return `The ${provider.id} provider cannot return images in tool results, so the model would never see a screenshot. Use a provider that can (for example Anthropic, Codex or Google) for computer use.`
+	if (!resolveProviderCapabilities(provider).supportsToolResultImages) {
+		return `The ${provider.id} provider cannot return images in tool results, so the model would never see a screenshot. Use a provider that can (for example Anthropic, Codex or Google) for computer use.`
+	}
+	// The driver can carry the image; the model behind it may still not read one.
+	// It would act on a screen it never saw, and the first screenshot would make
+	// the provider refuse every later request in the conversation.
+	if (model !== undefined && !modelReadsImages(provider, model)) {
+		return `The model ${model} cannot read images, so it would never see a screenshot. Use a model that reads images for computer use.`
+	}
+	return undefined
 }
 
 // ---------------------------------------------------------------------------

package/src/types/provider/errors.ts

@@ -270,6 +270,14 @@ export function readOutputOverflow(err: unknown): OutputOverflowFigures | undefi
 	return undefined
 }
 
+/** Undici's `TypeError: terminated` anywhere on the chain: the body stream was cut. */
+function isUndiciTermination(err: unknown): boolean {
+	for (const link of causeChain(err)) {
+		if ((link as unknown) instanceof TypeError && link.message === 'terminated') return true
+	}
+	return false
+}
+
 /** Node/undici transport failures that mean "never reached the model". */
 const NETWORK_ERRNOS: ReadonlySet<string> = new Set([
 	'ECONNRESET',
@@ -304,12 +312,19 @@ function codeFromStatus(status: number): ProviderErrorCode {
 	return 'unknown'
 }
 
+function overflowWordingAllowed(status: number | undefined): boolean {
+	return status === undefined || status === 400 || status === 413
+}
+
+const CONTEXT_WINDOW_OVERFLOW =
+	/(?:exceed\w*|too (?:long|large|big)|larger than|longer than|over the|beyond|maximum|overflow\w*)\b[^.]{0,60}context window|context window[^.]{0,60}\b(?:exceed\w*|too (?:long|large|big)|larger than|longer than|over the|beyond|maximum|overflow\w*)/i
+
 /**
  * Message sniffing is the LAST resort, used only when there is no status
  * and no errno. Vendors that tunnel a 400 through a 200 body (several
  * gateways do) are only reachable this way.
  */
-function codeFromMessage(message: string): ProviderErrorCode | undefined {
+function codeFromMessage(message: string, status?: number): ProviderErrorCode | undefined {
 	const m = message.toLowerCase()
 	if (
 		m.includes('context length') ||
@@ -322,6 +337,13 @@ function codeFromMessage(message: string): ProviderErrorCode | undefined {
 		// overflow rescue tests for by exact equality. The turn died holding
 		// the remedy.
 		m.includes('too long for') ||
+		// The reference terminal's own wordings (its `context window` and
+		// `input length and max_tokens exceed context limit` matchers).
+		// Only where the status cannot say otherwise: a 429, 5xx or 401 that
+		// mentions the window is still a rate limit, a server fault or an auth
+		// failure, and must keep its retry and fallback behaviour.
+		(overflowWordingAllowed(status) &&
+			(CONTEXT_WINDOW_OVERFLOW.test(message) || m.includes('exceed context limit'))) ||
 		m.includes('maximum length') ||
 		m.includes('exceeds the maximum') ||
 		m.includes('input is too large') ||
@@ -498,7 +520,9 @@ export function classifyProviderError(
 	// usually generic ("request failed") — so matching only the outer text
 	// looks at the one string least likely to say anything.
 	const messages = chainMessages(err)
-	const fromMessage = messages.map(codeFromMessage).find((code) => code !== undefined)
+	const fromMessage = messages
+		.map((m) => codeFromMessage(m, status))
+		.find((code) => code !== undefined)
 	// A first-hand statement from whoever produced the failure, if there
 	// is one. It outranks the code's inference, not the code itself: the
 	// classification still says WHAT went wrong.
@@ -522,7 +546,7 @@ export function classifyProviderError(
 
 	// A 400 that is really a window overflow must not be filed as a plain
 	// invalid_request: the caller can recover from one and not the other.
-	if (messages.some((m) => codeFromMessage(m) === 'context_length_exceeded')) {
+	if (messages.some((m) => codeFromMessage(m, status) === 'context_length_exceeded')) {
 		return new ProviderError({
 			code: 'context_length_exceeded',
 			message,
@@ -566,8 +590,12 @@ export function classifyProviderError(
 		}
 	}
 
-	// `fetch` rejects with a bare TypeError on transport failure.
-	if (err instanceof TypeError && /fetch|network/i.test(message)) {
+	// `fetch` rejects with a bare TypeError on transport failure, and undici
+	// ends a response body the peer cut mid-stream with `TypeError:
+	// terminated`. Its socket error normally rides along as the cause and the
+	// errno walk above catches it, but a vendor SDK that re-wraps the stream
+	// error can drop that cause and leave only the bare word.
+	if ((err instanceof TypeError && /fetch|network/i.test(message)) || isUndiciTermination(err)) {
 		return new ProviderError({
 			code: 'network',
 			message,

package/src/types/provider/interface.ts

@@ -22,6 +22,19 @@ export interface LLMProvider {
 	/** Refine hosted search support for a model and mode. Absent uses the driver-wide declaration. */
 	supportsHostedWebSearchFor?(model: string, mode: 'live' | 'cached'): boolean
 
+	/**
+	 * Whether `model` reads images. `capabilities.supportsVision` is a statement
+	 * about the DRIVER (does it map image parts onto the wire); this is about the
+	 * MODEL behind it, which only the driver's catalogue can know: one driver
+	 * serves vision and text-only models side by side, and a text-only model
+	 * refuses the whole request when it finds an image in it.
+	 *
+	 * Answer `false` only when the model is known to be text-only. Absent, or
+	 * `true`, means "send images": the runtime also recovers from a refusal, so a
+	 * driver with no catalogue loses nothing by omitting this.
+	 */
+	supportsImageInputFor?(model: string): boolean
+
 	/**
 	 * Retry behaviour this DRIVER wants, when the generic default is wrong
 	 * for the vendor behind it.

package/src/types/provider/stream.ts

@@ -174,7 +174,7 @@ export interface ProviderRetryNotice {
 	/** The delay came from the server's own `Retry-After`, not backoff. */
 	readonly serverDirected: boolean
 	/**
-	 * The failed attempt had already streamed text or reasoning, and the request
+	 * The failed attempt had already streamed text or reasoning (reasoning alone is retried without any option), and the request
 	 * is being sent again from the start. Whatever that attempt produced is void
 	 * and the consumer must drop it before the next chunk.
 	 */

package/src/types/session/config.ts

@@ -88,6 +88,20 @@ export interface TurnConfig {
 		 * behaviour every sandboxed turn had before this existed.
 		 */
 		workspace?: 'ephemeral' | 'working-directory'
+		/**
+		 * When the turn acquires its sandbox. Absent means `'eager'`: acquired,
+		 * and waited for, before the input guardrails and the first model
+		 * request.
+		 *
+		 * `'concurrent'` starts at the same point but lets the first model
+		 * request go out while the provider allocates; the first tool call
+		 * waits for the handle. `'on-first-use'` does not start until the first
+		 * tool call. Either way `sandbox_created` is emitted when the handle
+		 * arrives, and a failure or timeout ends the turn with the stop reason
+		 * an eager acquisition would have produced, at the first tool call or
+		 * at turn end, whichever comes first.
+		 */
+		acquire?: 'eager' | 'concurrent' | 'on-first-use'
 	}
 
 	/**

package/src/types/session/events.ts

@@ -280,8 +280,11 @@ type CoreSessionEvent =
 			 *   a provider that rejects the pairing. A reducer bug, and one
 			 *   `findSafeTrimIndex` exists to prevent.
 			 * - `breaker_open` — only with `compactionConfig.circuitBreaker`:
-			 *   three passes in a row failed, so automatic compaction is off for
-			 *   the rest of the turn. Sent once. `messages` is the live count.
+			 *   three passes in a row failed, so proactive compaction is off for
+			 *   the rest of the turn; a context overflow the provider reports
+			 *   still runs the reactive relief. Sent once, without `error`: it is
+			 *   for a host's records, not a line for the person. `messages` is
+			 *   the live count.
 			 * - `refilling` — only with `compactionConfig.circuitBreaker`: the
 			 *   context filled back up within three iterations of a compaction,
 			 *   three times in a row, and the turn is stopping. Sent once.
@@ -289,7 +292,7 @@ type CoreSessionEvent =
 			cause: 'reducer_threw' | 'shed_nothing' | 'split_tool_pair' | 'breaker_open' | 'refilling'
 			/** Unchanged, and stated so a reader need not infer it. */
 			messages: number
-			/** For `reducer_threw`, the reducer's message; for `breaker_open` and `refilling`, the one line to show. */
+			/** For `reducer_threw`, the reducer's message; for `refilling`, the one line to show. */
 			error?: string
 	  }
 	| {
@@ -714,9 +717,26 @@ type CoreSessionEvent =
 			sessionId: SessionId
 			turnId?: TurnId
 			capability: 'tools' | 'vision' | 'documents'
-			/** Present when the mismatch was produced after a tool executed. */
-			contentSource?: 'tool-result'
+			/**
+			 * Present when the mismatch was not about the user's own message:
+			 * `'tool-result'` after a tool executed; `'history'` when the model
+			 * itself turned out not to read images (see `model`) and the images
+			 * already in the conversation were left out of the request;
+			 * `'media-removed'` when the provider rejected an image or document
+			 * and it was left out of the request that then went through;
+			 * `'media-removed-current'` when that included a file attached to the
+			 * latest user message; `'media-limit'` when the oldest files were left
+			 * out only to fit a count the provider accepts.
+			 */
+			contentSource?:
+				| 'tool-result'
+				| 'history'
+				| 'media-removed'
+				| 'media-removed-current'
+				| 'media-limit'
 			providerId: string
+			/** The model that cannot read images, when the warning is about one model rather than the driver. */
+			model?: string
 			message: string
 	  }
 	/**