@namzu/sdk 31.1.0 → 32.0.0

package/src/runtime/query/iteration/provider-rejected-image.ts

@@ -0,0 +1,106 @@
+import { isProviderRequestError } from '../../../provider/errors.js'
+import type {
+	ChatCompletionParams,
+	LLMProvider,
+	StreamChunk,
+} from '../../../types/provider/index.js'
+import {
+	type RequestImageIdentity,
+	findSingleRequestImage,
+	projectRequestWithoutImage,
+} from '../request-rich-content.js'
+
+const IMAGE_REJECTION_PATTERNS: readonly RegExp[] = [
+	/\binvalid[_ -]?image\b/i,
+	/\bimage\b.{0,100}\b(?:cannot|could not|failed to)\s+(?:be\s+)?(?:decoded|processed|loaded|parsed|read)\b/i,
+	/\b(?:cannot|could not|failed to)\s+(?:decode|process|load|parse|read)\b.{0,100}\bimage\b/i,
+	/\bimage\b.{0,100}\b(?:malformed|corrupt|unsupported format)\b/i,
+]
+
+type ImageRejectionConfidence = 'server-confirmed' | 'heuristic'
+
+function classifyProviderRejectedImageError(error: unknown): ImageRejectionConfidence | null {
+	if (!isProviderRequestError(error) || error.kind !== 'bad_request') return null
+	if (error.status === 400 && error.providerCode === 'invalid_image') return 'server-confirmed'
+	const detail = error.detail ?? error.message
+	return IMAGE_REJECTION_PATTERNS.some((pattern) => pattern.test(detail)) ? 'heuristic' : null
+}
+
+export function isProviderRejectedImageError(error: unknown): boolean {
+	return classifyProviderRejectedImageError(error) !== null
+}
+
+function isAcceptedChunk(chunk: StreamChunk): boolean {
+	if (chunk.retry !== undefined || chunk.fallback !== undefined || chunk.error !== undefined) {
+		return false
+	}
+	return Boolean(
+		chunk.delta.content ||
+			chunk.delta.toolCalls?.length ||
+			chunk.delta.toolCallEnd ||
+			chunk.delta.reasoning ||
+			chunk.delta.citation ||
+			chunk.finishReason !== undefined ||
+			chunk.usage !== undefined ||
+			chunk.replayState !== undefined,
+	)
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+	if (signal?.aborted) throw signal.reason
+}
+
+/**
+ * Retry one provider-invalid request without its only distinct image.
+ *
+ * The callback is the durable commit point for an HTTP 400 carrying the exact
+ * provider code `invalid_image`. It runs only after the retry has produced an
+ * accepted chunk or reached a clean EOF. A legacy phrase can still recover the
+ * current request, but cannot assert durable server proof.
+ */
+export async function* streamWithProviderRejectedImageRecovery(
+	provider: LLMProvider,
+	params: ChatCompletionParams,
+	onAccepted: (identity: RequestImageIdentity) => Promise<void>,
+): AsyncIterable<StreamChunk> {
+	const candidate = findSingleRequestImage(params.messages)
+	if (candidate === null) {
+		yield* provider.chatStream(params)
+		return
+	}
+
+	let produced = false
+	let confidence: ImageRejectionConfidence | null = null
+	try {
+		for await (const chunk of provider.chatStream(params)) {
+			if (isAcceptedChunk(chunk)) produced = true
+			yield chunk
+		}
+		return
+	} catch (error) {
+		throwIfAborted(params.signal)
+		confidence = classifyProviderRejectedImageError(error)
+		if (produced || confidence === null) throw error
+	}
+
+	throwIfAborted(params.signal)
+	const retryParams: ChatCompletionParams = {
+		...params,
+		messages: projectRequestWithoutImage(params.messages, candidate),
+	}
+	let accepted = false
+	let retryReportedError = false
+	for await (const chunk of provider.chatStream(retryParams)) {
+		if (chunk.error !== undefined) retryReportedError = true
+		if (!accepted && isAcceptedChunk(chunk)) {
+			throwIfAborted(params.signal)
+			if (confidence === 'server-confirmed') await onAccepted(candidate)
+			accepted = true
+		}
+		yield chunk
+	}
+	if (!accepted && !retryReportedError) {
+		throwIfAborted(params.signal)
+		if (confidence === 'server-confirmed') await onAccepted(candidate)
+	}
+}

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

@@ -22,6 +22,8 @@ import type { MessageStopReason } from '../../../types/run/stop-reason.js'
 import { generateMessageId } 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'
 
 /**
  * Map a provider's coarse `finishReason` plus the orchestrator's
@@ -147,6 +149,9 @@ export async function* streamProviderTurn(
 	 * Optional, so a caller with no use for the id is unchanged.
 	 */
 	announceAs?: import('../../../types/ids/index.js').MessageId,
+	imageRecovery?: {
+		readonly onAccepted: (identity: RequestImageIdentity) => Promise<void>
+	},
 ): AsyncGenerator<RunEvent, StreamingTurnResult> {
 	// The `chat {model}` span the GenAI conventions require. There was none:
 	// `chatSpanName` existed with zero call sites, so a trace carried no LLM
@@ -224,10 +229,15 @@ export async function* streamProviderTurn(
 	let streamError: string | undefined
 	let streamCause: unknown
 
-	const stream = provider.chatStream({
+	const streamParams = {
 		...params,
 		stream: true,
-	}) as AsyncIterable<StreamChunk>
+	} satisfies import('../../../types/provider/index.js').ChatCompletionParams
+	const stream = (
+		imageRecovery
+			? streamWithProviderRejectedImageRecovery(provider, streamParams, imageRecovery.onAccepted)
+			: provider.chatStream(streamParams)
+	) as AsyncIterable<StreamChunk>
 
 	// Drive the stream manually so each `.next()` can be RACED against the run
 	// abort: a Stop tears the in-flight model request down (the provider got

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

@@ -34,6 +34,12 @@ interface RichOccurrence {
 	readonly source: 'user' | 'tool'
 	readonly kind: RichKind
 	readonly bytes: number
+	readonly reason: 'budget' | 'provider-rejected'
+}
+
+export interface RequestImageIdentity {
+	readonly data: string
+	readonly mediaType: string
 }
 
 const userMarker = (kind: RichKind): string =>
@@ -42,6 +48,12 @@ const userMarker = (kind: RichKind): string =>
 const toolMarker = (kind: RichKind): string =>
 	`[${kind} omitted from this model request to keep the accumulated rich-content payload within its configured size limit; call the producing tool again if it is still needed.]`
 
+const rejectedUserImageMarker = (): string =>
+	'[image omitted from this model request because the provider rejected this image; attach a corrected image in a new message if it is still needed.]'
+
+const rejectedToolImageMarker = (): string =>
+	'[image omitted from this model request because the provider rejected this image; call the producing tool again after correcting its image source if it is still needed.]'
+
 function assertInlineAttachment(
 	attachment: MessageAttachment,
 ): asserts attachment is Exclude<MessageAttachment, { readonly type: 'stored' }> {
@@ -65,6 +77,11 @@ function collectRichOccurrences(messages: readonly Message[]): RichOccurrence[]
 					source: 'user',
 					kind: attachment.type === 'document' ? 'document' : 'image',
 					bytes: attachment.data.length,
+					reason:
+						attachment.type !== 'document' &&
+						attachment.modelOmission?.reason === 'provider-rejected'
+							? 'provider-rejected'
+							: 'budget',
 				})
 			}
 			continue
@@ -79,6 +96,10 @@ function collectRichOccurrences(messages: readonly Message[]): RichOccurrence[]
 				source: 'tool',
 				kind: block.type,
 				bytes: block.data.length,
+				reason:
+					block.type === 'image' && block.modelOmission?.reason === 'provider-rejected'
+						? 'provider-rejected'
+						: 'budget',
 			})
 		}
 	}
@@ -86,10 +107,19 @@ function collectRichOccurrences(messages: readonly Message[]): RichOccurrence[]
 	return occurrences
 }
 
-function appendMarkers(content: string, kinds: readonly RichKind[]): string {
-	if (kinds.length === 0) return content
-	const markers = kinds.map(userMarker).join('\n\n')
-	return content.length > 0 ? `${content}\n\n${markers}` : markers
+function appendTextMarkers(content: string, markers: readonly string[]): string {
+	if (markers.length === 0) return content
+	const joined = markers.join('\n\n')
+	return content.length > 0 ? `${content}\n\n${joined}` : joined
+}
+
+function appendMarkers(content: string, occurrences: readonly RichOccurrence[]): string {
+	const markers = occurrences.map((occurrence) =>
+		occurrence.reason === 'provider-rejected'
+			? rejectedUserImageMarker()
+			: userMarker(occurrence.kind),
+	)
+	return appendTextMarkers(content, markers)
 }
 
 /**
@@ -103,15 +133,10 @@ function appendMarkers(content: string, kinds: readonly RichKind[]): string {
  */
 export function projectRequestRichContent(messages: Message[], maxBytes: number): Message[] {
 	const occurrences = collectRichOccurrences(messages)
-	if (maxBytes === 0 || occurrences.length === 0) return messages
-
-	let total = occurrences.reduce((sum, occurrence) => sum + occurrence.bytes, 0)
-	if (total <= maxBytes) return messages
+	if (occurrences.length === 0) return messages
 
 	const omitted = new Map<number, Map<number, RichOccurrence>>()
-	for (const occurrence of occurrences) {
-		if (total <= maxBytes) break
-		total -= occurrence.bytes
+	const omit = (occurrence: RichOccurrence): void => {
 		let byItem = omitted.get(occurrence.messageIndex)
 		if (!byItem) {
 			byItem = new Map()
@@ -120,6 +145,24 @@ export function projectRequestRichContent(messages: Message[], maxBytes: number)
 		byItem.set(occurrence.itemIndex, occurrence)
 	}
 
+	for (const occurrence of occurrences) {
+		if (occurrence.reason === 'provider-rejected') omit(occurrence)
+	}
+
+	let total = occurrences.reduce(
+		(sum, occurrence) => sum + (occurrence.reason === 'budget' ? occurrence.bytes : 0),
+		0,
+	)
+	if (maxBytes > 0 && total > maxBytes) {
+		for (const occurrence of occurrences) {
+			if (total <= maxBytes) break
+			if (occurrence.reason !== 'budget') continue
+			total -= occurrence.bytes
+			omit(occurrence)
+		}
+	}
+	if (omitted.size === 0) return messages
+
 	return messages.map((message, messageIndex) => {
 		const byItem = omitted.get(messageIndex)
 		if (!byItem) return message
@@ -127,13 +170,12 @@ export function projectRequestRichContent(messages: Message[], maxBytes: number)
 		if (message.role === 'user') {
 			const { attachments = [], ...withoutAttachments } = message
 			const kept = attachments.filter((_attachment, itemIndex) => !byItem.has(itemIndex))
-			const omittedKinds = [...byItem.values()]
+			const omittedOccurrences = [...byItem.values()]
 				.filter((occurrence) => occurrence.source === 'user')
 				.sort((a, b) => a.itemIndex - b.itemIndex)
-				.map((occurrence) => occurrence.kind)
 			return {
 				...withoutAttachments,
-				content: appendMarkers(message.content, omittedKinds),
+				content: appendMarkers(message.content, omittedOccurrences),
 				...(kept.length > 0 ? { attachments: kept } : {}),
 			}
 		}
@@ -142,7 +184,13 @@ export function projectRequestRichContent(messages: Message[], maxBytes: number)
 			const content: ToolResultBlock[] = message.content.map((block, itemIndex) => {
 				const occurrence = byItem.get(itemIndex)
 				return occurrence?.source === 'tool'
-					? { type: 'text', text: toolMarker(occurrence.kind) }
+					? {
+							type: 'text',
+							text:
+								occurrence.reason === 'provider-rejected'
+									? rejectedToolImageMarker()
+									: toolMarker(occurrence.kind),
+						}
 					: block
 			})
 			return { ...message, content }
@@ -151,3 +199,128 @@ export function projectRequestRichContent(messages: Message[], maxBytes: number)
 		return message
 	})
 }
+
+function sameImage(
+	image: { readonly data: string; readonly mediaType: string },
+	identity: RequestImageIdentity,
+): boolean {
+	return image.data === identity.data && image.mediaType === identity.mediaType
+}
+
+/** Find the one distinct image in the exact provider-bound request, if one exists. */
+export function findSingleRequestImage(messages: readonly Message[]): RequestImageIdentity | null {
+	let candidate: RequestImageIdentity | null = null
+	for (const message of messages) {
+		if (message.role === 'user') {
+			for (const attachment of message.attachments ?? []) {
+				if (attachment.type === 'stored') {
+					throw new TypeError(
+						'Cannot inspect an unresolved stored attachment at the provider boundary',
+					)
+				}
+				if (attachment.type === 'document') continue
+				if (candidate === null) {
+					candidate = { data: attachment.data, mediaType: attachment.mediaType }
+				} else if (!sameImage(attachment, candidate)) {
+					return null
+				}
+			}
+			continue
+		}
+		if (message.role !== 'tool' || !Array.isArray(message.content)) continue
+		for (const block of message.content) {
+			if (block.type !== 'image') continue
+			if (candidate === null) {
+				candidate = { data: block.data, mediaType: block.mediaType }
+			} else if (!sameImage(block, candidate)) {
+				return null
+			}
+		}
+	}
+	return candidate
+}
+
+/** Build the one-off retry request without changing durable conversation state. */
+export function projectRequestWithoutImage(
+	messages: Message[],
+	identity: RequestImageIdentity,
+): Message[] {
+	return messages.map((message) => {
+		if (message.role === 'user') {
+			const attachments = message.attachments ?? []
+			const rejected = attachments.filter(
+				(attachment) =>
+					attachment.type !== 'stored' &&
+					attachment.type !== 'document' &&
+					sameImage(attachment, identity),
+			)
+			if (rejected.length === 0) return message
+			const kept = attachments.filter(
+				(attachment) =>
+					attachment.type === 'stored' ||
+					attachment.type === 'document' ||
+					!sameImage(attachment, identity),
+			)
+			const { attachments: _attachments, ...withoutAttachments } = message
+			return {
+				...withoutAttachments,
+				content: appendTextMarkers(
+					message.content,
+					rejected.map(() => rejectedUserImageMarker()),
+				),
+				...(kept.length > 0 ? { attachments: kept } : {}),
+			}
+		}
+		if (message.role !== 'tool' || !Array.isArray(message.content)) return message
+		let changed = false
+		const content: ToolResultBlock[] = message.content.map((block) => {
+			if (block.type !== 'image' || !sameImage(block, identity)) return block
+			changed = true
+			return { type: 'text', text: rejectedToolImageMarker() }
+		})
+		return changed ? { ...message, content } : message
+	})
+}
+
+/** Persist a successful recovery while retaining exact image bytes. */
+export function markProviderRejectedImage(
+	messages: readonly Message[],
+	identity: RequestImageIdentity,
+): { readonly messages: Message[]; readonly count: number } {
+	let count = 0
+	const marked = messages.map((message) => {
+		if (message.role === 'user') {
+			let changed = false
+			const attachments = message.attachments?.map((attachment) => {
+				if (
+					attachment.type === 'stored' ||
+					attachment.type === 'document' ||
+					!sameImage(attachment, identity) ||
+					attachment.modelOmission?.reason === 'provider-rejected'
+				) {
+					return attachment
+				}
+				changed = true
+				count += 1
+				return { ...attachment, modelOmission: { reason: 'provider-rejected' as const } }
+			})
+			return changed ? { ...message, attachments } : message
+		}
+		if (message.role !== 'tool' || !Array.isArray(message.content)) return message
+		let changed = false
+		const content: ToolResultBlock[] = message.content.map((block) => {
+			if (
+				block.type !== 'image' ||
+				!sameImage(block, identity) ||
+				block.modelOmission?.reason === 'provider-rejected'
+			) {
+				return block
+			}
+			changed = true
+			count += 1
+			return { ...block, modelOmission: { reason: 'provider-rejected' as const } }
+		})
+		return changed ? { ...message, content } : message
+	})
+	return { messages: marked, count }
+}

package/src/runtime/query/result.ts

@@ -183,6 +183,7 @@ export class ResultAssembler {
 			? {
 					kind: err.kind,
 					providerId: err.providerId,
+					...(err.providerCode !== undefined ? { providerCode: err.providerCode } : {}),
 					...(err.status !== undefined ? { status: err.status } : {}),
 					...(err.retryAfterMs !== undefined ? { retryAfterMs: err.retryAfterMs } : {}),
 					// The provider's own sentence, already truncated and scrubbed

package/src/store/attachment/index.ts

@@ -60,6 +60,23 @@ export interface AttachmentOperationOptions {
 	readonly signal?: AbortSignal
 }
 
+/** Policy owned by the operation that materializes one or more references. */
+export interface AttachmentResolutionOptions extends AttachmentOperationOptions {
+	/**
+	 * Maximum wall-clock time for the complete materialization phase.
+	 *
+	 * Defaults to one minute. `0` retains the prior unbounded wait. The SDK
+	 * still races the wait itself, so a custom store cannot defeat this bound
+	 * by ignoring the signal it receives.
+	 */
+	readonly timeoutMs?: number
+}
+
+/** One minute is long enough for remote stores without letting a run wedge forever. */
+export const DEFAULT_ATTACHMENT_RESOLVE_TIMEOUT_MS = 60_000
+
+const MAX_TIMER_DELAY_MS = 2_147_483_647
+
 export interface AttachmentStore {
 	/**
 	 * Take bytes, return a ref.
@@ -109,6 +126,17 @@ export class AttachmentMediaTypeMismatchError extends Error {
 	}
 }
 
+/** A store did not settle the materialization phase within its declared bound. */
+export class AttachmentResolutionTimeoutError extends Error {
+	readonly details: { timeoutMs: number }
+
+	constructor(details: { timeoutMs: number }) {
+		super(`Stored attachment resolution timed out after ${details.timeoutMs}ms.`)
+		this.name = 'AttachmentResolutionTimeoutError'
+		this.details = details
+	}
+}
+
 export const isStoredAttachment = (
 	attachment: MessageAttachment,
 ): attachment is MessageAttachment & StoredAttachment =>
@@ -126,11 +154,23 @@ export const isStoredAttachment = (
 export async function resolveAttachment(
 	attachment: MessageAttachment,
 	store: AttachmentStore | undefined,
-	options: AttachmentOperationOptions = {},
+	options: AttachmentResolutionOptions = {},
 ): Promise<MessageAttachment> {
-	const { signal } = options
-	signal?.throwIfAborted()
+	options.signal?.throwIfAborted()
+	const timeoutMs = resolveAttachmentTimeoutMs(options.timeoutMs)
 	if (!isStoredAttachment(attachment)) return attachment
+
+	return await withAttachmentDeadline(options.signal, timeoutMs, async (signal) =>
+		resolveAttachmentWithSignal(attachment, store, signal),
+	)
+}
+
+async function resolveAttachmentWithSignal(
+	attachment: MessageAttachment & StoredAttachment,
+	store: AttachmentStore | undefined,
+	signal: AbortSignal | undefined,
+): Promise<MessageAttachment> {
+	signal?.throwIfAborted()
 	if (!store) throw new NoAttachmentStoreError({ ref: attachment.ref })
 
 	const bytes = await awaitStoreRead(signal, () =>
@@ -177,9 +217,10 @@ export async function resolveAttachment(
 export async function resolveAttachments(
 	messages: readonly Message[],
 	store: AttachmentStore | undefined,
-	options: AttachmentOperationOptions = {},
+	options: AttachmentResolutionOptions = {},
 ): Promise<readonly Message[]> {
 	options.signal?.throwIfAborted()
+	const timeoutMs = resolveAttachmentTimeoutMs(options.timeoutMs)
 	// `Message` rather than a structural constraint: only some members of
 	// the union carry `attachments`, and a structural bound over a union
 	// like that is not assignable in either direction. Naming the real type
@@ -189,20 +230,64 @@ export async function resolveAttachments(
 
 	if (!messages.some((m) => has(m)?.some(isStoredAttachment))) return messages
 
-	return await Promise.all(
-		messages.map(async (message) => {
-			const attachments = has(message)
-			if (!attachments?.some(isStoredAttachment)) return message
-			return {
-				...message,
-				attachments: await Promise.all(
-					attachments.map((attachment) => resolveAttachment(attachment, store, options)),
-				),
-			}
-		}),
+	return await withAttachmentDeadline(options.signal, timeoutMs, async (signal) =>
+		Promise.all(
+			messages.map(async (message) => {
+				const attachments = has(message)
+				if (!attachments?.some(isStoredAttachment)) return message
+				return {
+					...message,
+					attachments: await Promise.all(
+						attachments.map((attachment) =>
+							isStoredAttachment(attachment)
+								? resolveAttachmentWithSignal(attachment, store, signal)
+								: attachment,
+						),
+					),
+				}
+			}),
+		),
 	)
 }
 
+function resolveAttachmentTimeoutMs(value: number | undefined): number {
+	const resolved = value ?? DEFAULT_ATTACHMENT_RESOLVE_TIMEOUT_MS
+	if (!Number.isInteger(resolved) || resolved < 0 || resolved > MAX_TIMER_DELAY_MS) {
+		throw new RangeError(
+			`attachmentResolveTimeoutMs must be an integer from 0 to ${MAX_TIMER_DELAY_MS}; received ${String(resolved)}`,
+		)
+	}
+	return resolved
+}
+
+/**
+ * Own one timer for the whole parallel materialization phase.
+ *
+ * The caller's signal is an input, never the controller we abort. Whichever
+ * cause wins is latched by `AbortSignal.any`, and every store wait races that
+ * fused signal independently through `awaitStoreRead` below.
+ */
+async function withAttachmentDeadline<T>(
+	upstream: AbortSignal | undefined,
+	timeoutMs: number,
+	start: (signal: AbortSignal | undefined) => Promise<T>,
+): Promise<T> {
+	upstream?.throwIfAborted()
+	if (timeoutMs === 0) return await start(upstream)
+
+	const timeout = new AbortController()
+	const signal = upstream ? AbortSignal.any([upstream, timeout.signal]) : timeout.signal
+	const timer = setTimeout(
+		() => timeout.abort(new AttachmentResolutionTimeoutError({ timeoutMs })),
+		timeoutMs,
+	)
+	try {
+		return await start(signal)
+	} finally {
+		clearTimeout(timer)
+	}
+}
+
 /**
  * Await a host store without handing it ownership of run cancellation.
  *

package/src/tools/builtins/run-code.ts

@@ -99,19 +99,25 @@ export function buildRunCodeTool(options: RunCodeToolOptions = {}) {
 				timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
 				maxOutputBytes: options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT,
 				...(context.abortSignal ? { signal: context.abortSignal } : {}),
-				onHostCall: async (request) => {
+				onHostCall: async (request, operation) => {
 					// Through the SAME registry, with the SAME context. Not a
 					// parallel dispatch path: a second path is a second place
 					// for the permission gate to be forgotten, and the one that
 					// forgot it would be the one a model reached through a
 					// program.
 					try {
-						const toolResult = await dispatch(request.name, request.input)
+						const toolResult = await dispatch(request.name, request.input, {
+							signal: operation.signal,
+							runtimeToolCallId: operation.runtimeToolCallId,
+						})
 						return toolResult.success
 							? { ok: true, value: toolResult.output }
 							: { ok: false, error: toolResult.error ?? 'the tool failed' }
 					} catch (err) {
-						return { ok: false, error: err instanceof Error ? err.message : String(err) }
+						return {
+							ok: false,
+							error: err instanceof Error ? err.message : String(err),
+						}
 					}
 				},
 			})
@@ -142,10 +148,14 @@ export function buildRunCodeTool(options: RunCodeToolOptions = {}) {
 						// printed its progress and then hung has told the model
 						// where it got to, and discarding that leaves the model
 						// retrying from the start.
-						error: `The program ran longer than ${options.timeoutMs ?? DEFAULT_TIMEOUT_MS}ms and was stopped.`,
+						error: `The program ran longer than ${options.timeoutMs ?? DEFAULT_TIMEOUT_MS}ms and its worker was stopped. Admitted host calls were asked to cancel; an uncooperative one may still be running.`,
 					}
 				case 'cancelled':
-					return { success: false, output: body, error: 'The program was cancelled.' }
+					return {
+						success: false,
+						output: body,
+						error: 'The program was cancelled.',
+					}
 				default:
 					return { success: false, output: body, error: result.outcome.error }
 			}

package/src/types/agent/base.ts

@@ -23,6 +23,8 @@ export interface BaseAgentConfig {
 	streamIdleTimeoutMs?: number
 	/** See {@link import('../run/config.js').AgentRunConfig.maxRequestRichContentBytes}. */
 	maxRequestRichContentBytes?: number
+	/** Maximum stored-attachment materialization time; defaults to one minute. `0` disables. */
+	attachmentResolveTimeoutMs?: number
 	maxIterations?: number
 	temperature?: number
 	maxResponseTokens?: number
@@ -239,6 +241,8 @@ export interface AgentInput {
 	messages: Message[]
 	workingDirectory: string
 	signal?: AbortSignal
+	/** Store that owns any `stored` attachment refs carried by `messages`. */
+	attachmentStore?: import('../../store/attachment/index.js').AttachmentStore
 
 	taskStore?: TaskStore
 

package/src/types/agent/factory.ts

@@ -48,6 +48,7 @@ export interface AgentFactoryOptions {
 	timeoutMs?: number
 	streamIdleTimeoutMs?: number
 	maxRequestRichContentBytes?: number
+	attachmentResolveTimeoutMs?: number
 	temperature?: number
 	maxResponseTokens?: number
 	env?: Record<string, string>