@namzu/sdk 31.1.0 → 33.0.0

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' | 'invalid-image'
+}
+
+export interface RequestImageIdentity {
+	readonly data: string
+	readonly mediaType: string
 }
 
 const userMarker = (kind: RichKind): string =>
@@ -42,6 +48,18 @@ 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.]'
+
+const invalidUserImageMarker = (): string =>
+	'[image omitted from this model request because its encoded bytes are not a complete supported raster matching the declared media type; attach a corrected image in a new message if it is still needed.]'
+
+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; call the 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 +83,13 @@ 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 === 'invalid-image'
+							? 'invalid-image'
+							: attachment.type !== 'document' &&
+									attachment.modelOmission?.reason === 'provider-rejected'
+								? 'provider-rejected'
+								: 'budget',
 				})
 			}
 			continue
@@ -79,6 +104,12 @@ function collectRichOccurrences(messages: readonly Message[]): RichOccurrence[]
 				source: 'tool',
 				kind: block.type,
 				bytes: block.data.length,
+				reason:
+					block.type === 'image' && block.modelOmission?.reason === 'invalid-image'
+						? 'invalid-image'
+						: block.type === 'image' && block.modelOmission?.reason === 'provider-rejected'
+							? 'provider-rejected'
+							: 'budget',
 			})
 		}
 	}
@@ -86,10 +117,21 @@ 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()
+			: occurrence.reason === 'invalid-image'
+				? invalidUserImageMarker()
+				: userMarker(occurrence.kind),
+	)
+	return appendTextMarkers(content, markers)
 }
 
 /**
@@ -103,15 +145,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 +157,26 @@ export function projectRequestRichContent(messages: Message[], maxBytes: number)
 		byItem.set(occurrence.itemIndex, occurrence)
 	}
 
+	for (const occurrence of occurrences) {
+		if (occurrence.reason === 'provider-rejected' || occurrence.reason === 'invalid-image') {
+			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 +184,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 +198,15 @@ 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()
+									: occurrence.reason === 'invalid-image'
+										? invalidToolImageMarker()
+										: toolMarker(occurrence.kind),
+						}
 					: block
 			})
 			return { ...message, content }
@@ -151,3 +215,137 @@ 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/runtime/query/resume-pending.ts

@@ -1,8 +1,11 @@
+import { isDeepStrictEqual } from 'node:util'
+
 import type { RunPersistence } from '../../manager/run/persistence.js'
 import type {
 	CheckpointId,
 	HITLResumeDecision,
 	IterationCheckpoint,
+	ToolCallSummary,
 } from '../../types/hitl/index.js'
 import type { AssistantMessage, Message, ToolCall } from '../../types/message/index.js'
 import type { ChatCompletionResponse } from '../../types/provider/index.js'
@@ -38,6 +41,10 @@ export interface PendingResumePlan {
 	readonly response: ChatCompletionResponse
 	/** Per-call refusals derived from the decision. */
 	readonly denials: ToolCallDenials
+	/** Exact projections and gate decisions persisted with a tool review. */
+	readonly reviewedCalls?: readonly ToolCallSummary[]
+	/** Calls whose raw input the human replaced in the durable decision. */
+	readonly modifiedCallIds?: ReadonlySet<string>
 	/**
 	 * Answers to deliver to tools that parked on a question, keyed by the
 	 * asking call's id. Present only on a question resume.
@@ -117,6 +124,8 @@ export function planPendingResume(
 		assistant,
 		response: synthesizeResponse(assistant),
 		denials,
+		reviewedCalls: pending.request.toolCalls,
+		modifiedCallIds: modifiedCallIds(decision),
 	}
 }
 
@@ -246,13 +255,86 @@ export async function applyPendingResume(
 	executor: ToolExecutor,
 	prior?: PriorToolResults,
 ): Promise<void> {
+	const denials = new Map(plan.denials)
+	const reviewedById = new Map(plan.reviewedCalls?.map((call) => [call.id, call]))
+
+	// A gate denial belongs to the run, not to the process that first evaluated
+	// it. Restore it before preparation so denied calls do not even reach a
+	// pre-tool hook after restart.
+	for (const call of plan.reviewedCalls ?? []) {
+		if (call.authorization?.decision !== 'deny' || denials.has(call.id)) continue
+		denials.set(
+			call.id,
+			`Blocked by the authorization gate: ${call.authorization.reason ?? 'the persisted operator policy denied this call'}`,
+		)
+	}
+
+	const callsToPrepare = (plan.response.message.toolCalls ?? []).filter(
+		(call) => !prior?.has(call.id) && !denials.has(call.id),
+	)
+	const responseToPrepare: ChatCompletionResponse = {
+		...plan.response,
+		message: { ...plan.response.message, toolCalls: callsToPrepare },
+	}
+	const preparedBatch = await executor.prepareBatchForReview(responseToPrepare)
+
+	for (const call of preparedBatch.reviewCalls) {
+		const reviewed = reviewedById.get(call.id)
+		const wasModified = plan.modifiedCallIds?.has(call.id) === true
+		if (reviewed && !wasModified) {
+			const unchanged = reviewed.name === call.name && isDeepStrictEqual(reviewed.input, call.input)
+			if (!unchanged) {
+				const reason =
+					'The tool input changed after its durable review; the earlier approval cannot be reused.'
+				denials.set(call.id, reason)
+				await runMgr.recordAudit({
+					what: { action: 'tool_call', tool: call.name },
+					outcome: 'refused',
+					reason,
+				})
+				continue
+			}
+		}
+
+		const current = executor.evaluatePreparedAuthorization(call.name, call.input)
+		let reason: string | undefined
+		if (current?.decision === 'deny') {
+			reason = `Blocked by the authorization gate after resume: ${current.reason}`
+		} else if (current?.decision === 'review' && (wasModified || !reviewed)) {
+			reason = wasModified
+				? `Blocked by the authorization gate after resume: the modified prepared value requires a new explicit approval. ${current.reason}`
+				: `Blocked by the authorization gate after resume: this recovered call requires operator review. ${current.reason}`
+		} else if (!current && reviewed && reviewed.authorization === undefined) {
+			reason =
+				'The durable review predates bound authorization metadata; review this call again before execution.'
+		}
+
+		if (reason) {
+			denials.set(call.id, reason)
+			await runMgr.recordAudit({
+				what: { action: 'tool_call', tool: call.name },
+				outcome: 'refused',
+				reason,
+			})
+		}
+	}
+
 	runMgr.pushMessage(plan.assistant)
-	const batch = await executor.executeBatch(plan.response, plan.denials, prior)
+	const batch = await executor.executeBatch(plan.response, denials, prior, preparedBatch)
 	for (const msg of batch.messages) {
 		runMgr.pushMessage(msg)
 	}
 }
 
+function modifiedCallIds(decision: HITLResumeDecision): ReadonlySet<string> {
+	if (decision.action !== 'modify_tools') return new Set()
+	return new Set(
+		decision.modifications
+			.filter((modification) => modification.action === 'modify')
+			.map((modification) => modification.toolCallId),
+	)
+}
+
 /**
  * Results the run already produced for calls in `toolCalls`.
  *

package/src/runtime/query/tool-output-budget.ts

@@ -37,6 +37,57 @@ export const SPILL_MARKER = 'The full output was written to:'
  */
 const HEAD_SHARE = 0.75
 
+function safeHead(text: string, maxChars: number): string {
+	let end = Math.min(text.length, Math.max(0, maxChars))
+	if (end > 0) {
+		const last = text.charCodeAt(end - 1)
+		if (last >= 0xd800 && last <= 0xdbff) end--
+	}
+	return text.slice(0, end)
+}
+
+function safeTail(text: string, maxChars: number): string {
+	let start = Math.max(0, text.length - Math.max(0, maxChars))
+	if (start < text.length) {
+		const first = text.charCodeAt(start)
+		if (first >= 0xdc00 && first <= 0xdfff) start++
+	}
+	return text.slice(start)
+}
+
+/**
+ * Fit a recoverable head+tail preview inside the actual model-visible cap.
+ *
+ * The old implementation allocated the entire cap to source text and then
+ * appended its diagnostic and recovery instructions. A configured 1,000
+ * character cap therefore emitted 1,200–1,300 characters; at very small
+ * limits the explanation could be several times larger than the limit.
+ */
+function boundedPreview(
+	output: string,
+	maxChars: number,
+	toolName: string,
+	recovery: string,
+): string {
+	const detailedMiddle = [
+		'',
+		`[... characters omitted — "${toolName}" returned ${output.length.toLocaleString()} characters, over the ${maxChars.toLocaleString()}-character budget ...]`,
+		recovery,
+		'',
+	].join('\n')
+	const compactMiddle = '\n[... omitted ...]\n'
+	const middle = detailedMiddle.length < maxChars ? detailedMiddle : compactMiddle
+
+	// A host may deliberately set a tiny positive cap. At that point no
+	// truthful recovery sentence fits; the hard bound still wins.
+	if (middle.length >= maxChars) return safeHead(middle, maxChars)
+
+	const sourceChars = maxChars - middle.length
+	const headChars = Math.max(1, Math.floor(sourceChars * HEAD_SHARE))
+	const tailChars = Math.max(0, sourceChars - headChars)
+	return `${safeHead(output, headChars)}${middle}${safeTail(output, tailChars)}`
+}
+
 export interface ToolOutputBudgetResult {
 	/** What the model sees. */
 	readonly output: string
@@ -127,15 +178,6 @@ export function applyToolOutputBudget(opts: ApplyToolOutputBudgetOptions): ToolO
 		return { output, originalLength, truncated: false }
 	}
 
-	// Both slices are derived from `maxChars` so the preview honours the
-	// budget it is enforcing. `slice(-0)` returns the WHOLE string, so the
-	// zero-tail case must be branched, not computed.
-	const headChars = Math.max(1, Math.floor(maxChars * HEAD_SHARE))
-	const tailChars = Math.max(0, maxChars - headChars)
-	const head = output.slice(0, headChars)
-	const tail = tailChars > 0 ? output.slice(-tailChars) : ''
-	const omitted = originalLength - head.length - tail.length
-
 	const spillPath = opts.spillDir
 		? spill(opts.spillDir, opts.toolUseId, output, opts.onError)
 		: undefined
@@ -148,14 +190,7 @@ export function applyToolOutputBudget(opts: ApplyToolOutputBudgetOptions): ToolO
 		: 'The full output was not retained. Re-run with a narrower query, a line range, or a filter.'
 
 	return {
-		output: [
-			head,
-			'',
-			`[... ${omitted.toLocaleString()} characters omitted — "${opts.toolName}" returned ${originalLength.toLocaleString()} characters, over the ${maxChars.toLocaleString()}-character budget ...]`,
-			recovery,
-			'',
-			tail,
-		].join('\n'),
+		output: boundedPreview(output, maxChars, opts.toolName, recovery),
 		originalLength,
 		truncated: true,
 		...(spillPath ? { spillPath } : {}),

package/src/runtime/query/tooling.ts

@@ -1,8 +1,10 @@
+import type { AuthorizationGate } from '../../authorization/gate.js'
 import type { PluginLifecycleManager } from '../../plugin/lifecycle.js'
 import type { ActivityStore } from '../../store/activity/memory.js'
 import type { RunId } from '../../types/ids/index.js'
 import type { InvocationState } from '../../types/invocation/index.js'
 import type { PermissionMode } from '../../types/permission/index.js'
+import type { AuditEventInput } from '../../types/run/audit.js'
 import type { RunEvent } from '../../types/run/index.js'
 import type {
 	RequestToolPause,
@@ -41,6 +43,10 @@ export interface ToolingBootstrapConfig {
 	maxToolContentBytes?: number
 	toolOutputDir?: string
 	repairToolCall?: RepairToolCall
+	/** Operator authorization shared with the direct-call review path. */
+	authorizationGate?: AuthorizationGate
+	/** Durable refusal recorder for nested authorization decisions. */
+	recordAudit?: (input: AuditEventInput) => Promise<unknown>
 	/** Builds the durable-pause seam for one tool call; see ToolContext.requestPause. */
 	toolPause?: (toolUseId: string) => RequestToolPause
 }
@@ -81,6 +87,10 @@ export class ToolingBootstrap {
 					: {}),
 				...(config.toolOutputDir !== undefined ? { toolOutputDir: config.toolOutputDir } : {}),
 				...(config.repairToolCall !== undefined ? { repairToolCall: config.repairToolCall } : {}),
+				...(config.authorizationGate !== undefined
+					? { authorizationGate: config.authorizationGate }
+					: {}),
+				...(config.recordAudit !== undefined ? { recordAudit: config.recordAudit } : {}),
 				...(config.toolPause !== undefined ? { toolPause: config.toolPause } : {}),
 			},
 			activityStore,