@namzu/sdk 33.0.0 → 33.1.0

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

@@ -106,6 +106,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': {
@@ -198,6 +230,15 @@ export function createComputerUseTool(host: ComputerUseHost): ToolDefinition<Act
 		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
 
 /**