@namzu/sdk 33.0.0 → 33.1.1

package/src/runtime/query/iteration/index.ts

@@ -7,6 +7,7 @@ import {
 	STRUCTURED_OUTPUT_REPROMPT,
 } from '../../../constants/tools/index.js'
 import { renderSkillsSection } from '../../../persona/assembler.js'
+import { resolveProviderCapabilities } from '../../../provider/capabilities.js'
 import { collectChatCompletion } from '../../../provider/collect-chat-completion.js'
 import { formatCompletionNotification } from '../../../scheduler/completion-inbox.js'
 import {
@@ -19,8 +20,10 @@ import { getTracer } from '../../../telemetry/runtime-accessors.js'
 import { STRUCTURED_OUTPUT_TOOL_NAME } from '../../../tools/builtins/structuredOutput.js'
 import { DELEGATION_TIMEOUT_MS } from '../../../tools/coordinator/index.js'
 import type { CostInfo, TokenUsage } from '../../../types/common/index.js'
+import { NamzuError } from '../../../types/errors/index.js'
 import type { MessageId } from '../../../types/ids/index.js'
 import {
+	type Message,
 	createAssistantMessage,
 	createRuntimeContextMessage,
 	createSystemMessage,
@@ -148,6 +151,8 @@ export class IterationOrchestrator {
 	 * one process must not suppress each other's first envelope.
 	 */
 	private lastEnvelopeKey: string | undefined
+	/** Rich tool blocks already reported; durable history is scanned every turn. */
+	private readonly warnedRichToolResults = new Set<string>()
 	/**
 	 * The previous iteration held a `stopWhen` decision open for a worker.
 	 *
@@ -168,6 +173,70 @@ export class IterationOrchestrator {
 		this.ctx = ctx
 	}
 
+	/**
+	 * Check the exact post-budget request for tool-result shapes the active driver
+	 * cannot carry. Initial capability negotiation cannot see results produced by
+	 * a later tool turn, so this boundary runs immediately before every provider
+	 * call. Keys are durable call/block coordinates, which prevents old history
+	 * from warning again on every subsequent iteration.
+	 */
+	private async reportUnsupportedToolResults(messages: readonly Message[]): Promise<void> {
+		const capabilities =
+			this.ctx.providerCapabilities ?? resolveProviderCapabilities(this.ctx.provider)
+		const images: string[] = []
+		const documents: string[] = []
+		for (const message of messages) {
+			if (message.role !== 'tool' || !Array.isArray(message.content)) continue
+			for (const [index, block] of message.content.entries()) {
+				const key = `${message.toolCallId}:${index}:${block.type}`
+				if (this.warnedRichToolResults.has(key)) continue
+				if (block.type === 'image' && !capabilities.supportsToolResultImages) {
+					images.push(key)
+				}
+				if (block.type === 'document' && !capabilities.supportsToolResultDocuments) {
+					documents.push(key)
+				}
+			}
+		}
+
+		const report = async (
+			keys: readonly string[],
+			capability: 'vision' | 'documents',
+			label: 'image' | 'document',
+		): Promise<void> => {
+			if (keys.length === 0) return
+			const message = `Provider '${this.ctx.provider.id}' declares it cannot map ${label} tool results, but this request carries ${keys.length} new ${label} block(s). The model will receive the driver's explicit text fallback instead of that content.`
+			if (this.ctx.strictCapabilities) {
+				throw new NamzuError({
+					code: 'capability_unavailable',
+					message,
+					details: {
+						providerId: this.ctx.provider.id,
+						capability,
+						blockCount: keys.length,
+					},
+				})
+			}
+			for (const key of keys) this.warnedRichToolResults.add(key)
+			this.ctx.log.warn('Capability mismatch: the provider cannot map rich tool results', {
+				'namzu.capability.detail': message,
+				[GENAI.SYSTEM]: this.ctx.provider.id,
+				'namzu.runtime.rich_tool_result_count': keys.length,
+			})
+			await this.ctx.emitEvent({
+				type: 'capability_warning',
+				runId: this.ctx.runMgr.id,
+				capability,
+				contentSource: 'tool-result',
+				providerId: this.ctx.provider.id,
+				message,
+			})
+		}
+
+		await report(images, 'vision', 'image')
+		await report(documents, 'documents', 'document')
+	}
+
 	/**
 	 * Adopt the run's span after construction.
 	 *
@@ -459,6 +528,8 @@ export class IterationOrchestrator {
 						requestHistory,
 						this.ctx.runConfig.maxRequestRichContentBytes ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
 					)
+					await this.reportUnsupportedToolResults(messages)
+					yield* this.ctx.drainPending()
 
 					// What the model is about to be ASKED, recorded when it
 					// changed. `run_started` carries one system prompt and tool
@@ -1986,6 +2057,7 @@ export class IterationOrchestrator {
 				finalHistory,
 				this.ctx.runConfig.maxRequestRichContentBytes ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
 			)
+			await this.reportUnsupportedToolResults(finalMessages)
 
 			// Same cache discipline as the forced-final iteration: keep the
 			// tools param identical to prior iterations (cache prefix intact,

package/src/runtime/query/iteration/phases/context.ts

@@ -7,6 +7,7 @@ import { NAMZU } from '../../../../constants/telemetry/index.js'
 import type { PlanManager } from '../../../../manager/plan/lifecycle.js'
 import type { RunPersistence } from '../../../../manager/run/persistence.js'
 import type { PromptContributionRegistry } from '../../../../prompt/contributions.js'
+import type { ResolvedProviderCapabilities } from '../../../../provider/capabilities.js'
 import type { ServingMember } from '../../../../provider/fallback.js'
 import type { CompletionInbox } from '../../../../scheduler/completion-inbox.js'
 import type { ActivityStore } from '../../../../store/activity/memory.js'
@@ -44,6 +45,10 @@ import type { ToolGrantSet } from '../../tool-grants.js'
 
 export interface IterationContext {
 	readonly provider: LLMProvider
+	/** Driver-level request shapes negotiated for this run. */
+	readonly providerCapabilities?: ResolvedProviderCapabilities
+	/** Refuse a capability mismatch instead of emitting a warning and degrading. */
+	readonly strictCapabilities?: boolean
 	/**
 	 * Which chain member `provider` will route the NEXT request to.
 	 *

package/src/runtime/query/result.ts

@@ -140,6 +140,28 @@ export class ResultAssembler {
 		// later, discarding every field of it. `toPlatformError` is the
 		// projection that was written for exactly this and had no callers.
 		const failure = toPlatformError(err)
+		// The driver's classification and the operator explanation describe the
+		// throwable, not the terminal verdict. Compute them before choosing paused
+		// versus failed so a recoverable run does not become the one path that
+		// discards the reason and remedy a host needs in order to recover it.
+		const providerError = isProviderRequestError(err)
+			? {
+					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
+					// by the driver. Without it a host rendering this metadata
+					// knows a request was rejected but not which field, and has to
+					// re-parse prose to find out.
+					...(err.detail !== undefined ? { detail: err.detail } : {}),
+				}
+			: undefined
+		// Classification is structural; remediation is editorial. The catalog is
+		// optional because inventing advice for an uncharacterised failure is worse
+		// than presenting the reason alone.
+		const explanation = explainError(err) ?? undefined
 
 		// A transient failure that survived every in-turn recovery is not the
 		// same thing as a bad API key, and settling both as `failed` gave the
@@ -157,6 +179,9 @@ export class ResultAssembler {
 				runId: runMgr.id,
 				checkpointId: resumeFrom,
 				reason: errorMessage,
+				failure,
+				...(providerError ? { providerError } : {}),
+				...(explanation ? { explanation } : {}),
 			})
 			yield* drainPending()
 
@@ -177,35 +202,12 @@ export class ResultAssembler {
 			return
 		}
 
-		// The driver's classification, carried onto the run so a host can
-		// branch on WHAT failed without re-parsing a sentence.
-		const providerError = isProviderRequestError(err)
-			? {
-					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
-					// by the driver. Without it a host rendering this metadata
-					// knows a request was rejected but not which field, and has to
-					// go re-parse `error` to find out — which is exactly the
-					// re-parsing the line above says this exists to avoid.
-					...(err.detail !== undefined ? { detail: err.detail } : {}),
-				}
-			: undefined
 		runMgr.markFailed(errorMessage, providerError)
 
 		if (planManager.isActive) {
 			planManager.failPlan(errorMessage)
 		}
 
-		// The classification says what kind of failure it is; the catalog
-		// says what a person should do about it. Keeping them separate is the
-		// point — classification is structural and belongs at the boundary,
-		// remediation is editorial and belongs in a list a human appends to.
-		const explanation = explainError(err) ?? undefined
-
 		// Same terminal-verdict recording as the success path in completeRun —
 		// see LOG-14, design §5. Placed AFTER the early `resumeFrom !== undefined`
 		// return above, so a paused/resumable run is never audited as 'failure'.

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

@@ -43,6 +43,60 @@ const actionSchema = z.discriminatedUnion('type', [
 	z.object({ type: z.literal('key'), keys: z.string() }),
 ])
 
+/**
+ * The provider-facing shape is deliberately flat.
+ *
+ * The runtime schema above is the authoritative contract: it knows which
+ * fields each action requires. Rendering that discriminated union produces a
+ * root `anyOf`, however, and some custom-tool wires reject root combinators
+ * even when every branch is an object. A model can still see every field and
+ * every action here; incomplete combinations are rejected by `actionSchema`
+ * before the host is called, with the recovery hint below.
+ */
+const pointModelInputSchema = {
+	type: 'object',
+	properties: {
+		x: { type: 'integer' },
+		y: { type: 'integer' },
+	},
+	required: ['x', 'y'],
+	additionalProperties: false,
+} as const
+
+const modelInputSchema: Record<string, unknown> = {
+	type: 'object',
+	properties: {
+		type: {
+			type: 'string',
+			enum: [
+				'screenshot',
+				'cursor_position',
+				'mouse_move',
+				'mouse_click',
+				'mouse_drag',
+				'scroll',
+				'type_text',
+				'key',
+			],
+			description:
+				'Desktop action. screenshot and cursor_position need no other fields; mouse_move needs to; mouse_click needs at and button; mouse_drag needs from, to, and button; scroll needs at, direction, and amount; type_text needs text; key needs keys.',
+		},
+		to: pointModelInputSchema,
+		at: pointModelInputSchema,
+		from: pointModelInputSchema,
+		button: { type: 'string', enum: ['left', 'right', 'middle'] },
+		direction: { type: 'string', enum: ['up', 'down', 'left', 'right'] },
+		amount: { type: 'integer', description: 'Positive integer scroll distance.' },
+		text: { type: 'string', description: 'Literal text to type.' },
+		keys: {
+			type: 'string',
+			description: 'Key or key chord to press, for example ENTER or CTRL+R.',
+		},
+	},
+	required: ['type'],
+	additionalProperties: false,
+}
+
 /**
  * The tool's input, inferred from its schema.
  *
@@ -106,6 +160,38 @@ function buildDescription(host: ComputerUseHost): string {
 	return lines.join(' ')
 }
 
+function pointLabel(point: { readonly x: number; readonly y: number }): string {
+	return `(${point.x}, ${point.y})`
+}
+
+function quotedText(value: string): string {
+	const oneLine = value.replace(/\s+/g, ' ')
+	const visible = oneLine.length > 64 ? `${oneLine.slice(0, 63)}…` : oneLine
+	return JSON.stringify(visible)
+}
+
+/** Human activity text; the raw action union remains the model-facing input. */
+function actionLabel(input: ActionInput): string {
+	switch (input.type) {
+		case 'screenshot':
+			return 'Capture screenshot'
+		case 'cursor_position':
+			return 'Read cursor position'
+		case 'mouse_move':
+			return `Move pointer to ${pointLabel(input.to)}`
+		case 'mouse_click':
+			return `Click ${input.button} at ${pointLabel(input.at)}`
+		case 'mouse_drag':
+			return `Drag ${input.button} from ${pointLabel(input.from)} to ${pointLabel(input.to)}`
+		case 'scroll':
+			return `Scroll ${input.direction} ${input.amount} at ${pointLabel(input.at)}`
+		case 'type_text':
+			return `Type ${quotedText(input.text)}`
+		case 'key':
+			return `Press ${input.keys}`
+	}
+}
+
 function resultToToolResult(result: ComputerUseResult): ToolResult {
 	switch (result.type) {
 		case 'screenshot': {
@@ -193,11 +279,23 @@ export function createComputerUseTool(host: ComputerUseHost): ToolDefinition<Act
 		name: COMPUTER_USE_TOOL_NAME,
 		description: buildDescription(host),
 		inputSchema: actionSchema,
+		modelInputSchema: structuredClone(modelInputSchema),
+		validationErrorHint:
+			'Action requirements: mouse_move needs "to"; mouse_click needs "at" and "button"; mouse_drag needs "from", "to", and "button"; scroll needs "at", "direction", and positive "amount"; type_text needs "text"; key needs "keys".',
 		category: 'custom',
 		permissions: [],
 		readOnly: false,
 		destructive: (input: ActionInput) => DESTRUCTIVE_ACTION_TYPES.has(input.type),
 		concurrencySafe: false,
+		presentCall: (input) => ({
+			kind: 'generic',
+			label: actionLabel(input),
+			presentation: 'activity',
+		}),
+		presentResult: (_input, result) =>
+			result.success && result.output.trim().toLowerCase() === 'ok'
+				? { kind: 'generic', label: result.output, visibility: 'hidden' }
+				: undefined,
 
 		async execute(input, _context): Promise<ToolResult> {
 			const required = requiredCapability(input.type)

package/src/types/errors/catalog.ts

@@ -1,4 +1,4 @@
-import { ProviderError } from '../provider/errors.js'
+import { ProviderError, classifyProviderError } from '../provider/errors.js'
 import { isNamzuError } from './index.js'
 
 /**
@@ -84,13 +84,21 @@ export function factsOf(err: unknown): ErrorFacts {
 	const hint = readHint(err)
 	const message = err instanceof Error ? err.message : String(err)
 
-	if (err instanceof ProviderError) {
+	const providerFailure =
+		err instanceof ProviderError
+			? err
+			: err instanceof Error && err.name === 'ProviderRequestError'
+				? classifyProviderError(err)
+				: undefined
+	if (providerFailure) {
 		return {
-			code: err.code,
+			code: providerFailure.code,
 			message,
-			name: err.name,
-			...(err.status !== undefined ? { status: err.status } : {}),
-			...(err.retryAfterMs !== undefined ? { retryAfterMs: err.retryAfterMs } : {}),
+			name: providerFailure.name,
+			...(providerFailure.status !== undefined ? { status: providerFailure.status } : {}),
+			...(providerFailure.retryAfterMs !== undefined
+				? { retryAfterMs: providerFailure.retryAfterMs }
+				: {}),
 			...(hint !== undefined ? { hint } : {}),
 		}
 	}

package/src/types/errors/index.ts

@@ -1,5 +1,5 @@
 import type { PlatformError } from '../common/index.js'
-import { ProviderError } from '../provider/errors.js'
+import { ProviderError, classifyProviderError } from '../provider/errors.js'
 
 /**
  * What went wrong, at the granularity a HOST actually branches on.
@@ -97,17 +97,31 @@ export function toPlatformError(err: unknown): PlatformError {
 		}
 	}
 
-	if (err instanceof ProviderError) {
+	// Current drivers throw `ProviderRequestError`; older/custom providers may
+	// throw `ProviderError`. The retry layer already classifies both through the
+	// shared function below, but this terminal projection used to recognise only
+	// the older class and turn a first-hand 429 into unknown/non-retryable.
+	const providerFailure =
+		err instanceof ProviderError
+			? err
+			: err instanceof Error && err.name === 'ProviderRequestError'
+				? classifyProviderError(err)
+				: undefined
+	if (providerFailure) {
 		return {
 			code: 'provider_error',
-			message: err.message,
+			message: providerFailure.message,
 			details: {
-				providerCode: err.code,
-				...(err.providerId !== undefined ? { providerId: err.providerId } : {}),
-				...(err.status !== undefined ? { status: err.status } : {}),
-				...(err.retryAfterMs !== undefined ? { retryAfterMs: err.retryAfterMs } : {}),
+				providerCode: providerFailure.code,
+				...(providerFailure.providerId !== undefined
+					? { providerId: providerFailure.providerId }
+					: {}),
+				...(providerFailure.status !== undefined ? { status: providerFailure.status } : {}),
+				...(providerFailure.retryAfterMs !== undefined
+					? { retryAfterMs: providerFailure.retryAfterMs }
+					: {}),
 			},
-			retryable: err.retryable,
+			retryable: providerFailure.retryable,
 		}
 	}
 

package/src/types/provider/config.ts

@@ -138,6 +138,15 @@ export interface ProviderCapabilities {
 	 * treated as capable, same permissive default.
 	 */
 	supportsDocuments?: boolean
+	/**
+	 * Whether the driver maps image blocks returned by tools onto its tool-result
+	 * wire. Separate from `supportsVision`: some protocols admit user image input
+	 * but only text in a function result. Absent keeps the permissive compatibility
+	 * default used by the older flags.
+	 */
+	supportsToolResultImages?: boolean
+	/** Whether the driver maps document blocks returned by tools onto its result wire. */
+	supportsToolResultDocuments?: boolean
 	maxOutputTokens?: number
 }
 

package/src/types/run/events.ts

@@ -505,6 +505,17 @@ type CoreRunEvent =
 			runId: RunId
 			checkpointId: CheckpointId
 			reason: string
+			/**
+			 * The same structured failure projection a terminal `run_failed`
+			 * carries. A pause is a different verdict, not a less informative one:
+			 * the retryability and any provider-directed delay are what let a host
+			 * decide when and how to resume this checkpoint.
+			 */
+			failure?: PlatformError
+			/** First-hand driver classification, when the provider produced one. */
+			providerError?: import('../provider/error.js').ProviderErrorInfo
+			/** Curated operator copy, absent when no catalog rule matched. */
+			explanation?: { id: string; message: string; hint: string }
 	  }
 	| {
 			type: 'run_resuming'
@@ -593,13 +604,16 @@ type CoreRunEvent =
 	// run when the request asks for something the provider DRIVER declared
 	// it cannot do — tools registered against a no-tools driver (tool
 	// surfaces stripped so the model is never told about uncallable
-	// tools), image attachments against a no-vision driver, or document
-	// attachments against a no-documents driver. Hosts surface these so
-	// degradation is visible, not silent.
+	// tools), image attachments against a no-vision driver, document
+	// attachments against a no-documents driver, or rich tool blocks against a
+	// result wire that only carries text. Hosts surface these so degradation is
+	// visible, not silent.
 	| {
 			type: 'capability_warning'
 			runId: RunId
 			capability: 'tools' | 'vision' | 'documents'
+			/** Present when the mismatch was produced after a tool executed. */
+			contentSource?: 'tool-result'
 			providerId: string
 			message: string
 	  }

package/src/types/tool/presentation.ts

@@ -11,13 +11,20 @@ import type { ToolResult } from './index.js'
  * the raw arguments and rebuilt the same switch.
  *
  * The tool knows what it is doing; the host knows how its surface renders.
- * These are the three shapes one host had already found it needed, closed
+ * These are the shapes hosts have agreed to render, closed
  * deliberately: an open union would let a tool ask for a rendering no host
  * has, which is a request that fails silently at the far end.
  */
 export type ToolCallView =
 	/** A line of text. What everything that is not a diff or a command gets. */
-	| { readonly kind: 'generic'; readonly label: string }
+	| {
+			readonly kind: 'generic'
+			readonly label: string
+			/** Render this complete authored label without adding the registry name. */
+			readonly presentation?: 'activity'
+			/** A successful result may add no information beyond the completed call row. */
+			readonly visibility?: 'hidden'
+	  }
 	/**
 	 * A change to a document. `path` is optional because not every diff is
 	 * a file — a tool patching a remote record has a before and an after
@@ -32,7 +39,7 @@ export type ToolCallView =
 	/** A command and what it printed. */
 	| { readonly kind: 'terminal'; readonly command?: string; readonly output: string }
 
-/** The same three shapes, for what a call produced. */
+/** The same shapes, for what a call produced. */
 export type ToolResultView = ToolCallView
 
 /**