@namzu/sdk 32.0.0 → 33.1.0

package/dist/utils/abort.js

@@ -1,3 +1,4 @@
+import { EventEmitter } from 'node:events';
 import { toErrorMessage } from './error.js';
 /**
  * The words a caller attached to a stop, or nothing when there were none.
@@ -44,6 +45,21 @@ export function abortReasonText(reason) {
     const text = toErrorMessage(reason).trim();
     return text.length > 0 ? text : undefined;
 }
+/**
+ * Subscribe to caller cancellation without raising the Node 20.0 runtime floor.
+ *
+ * `addAbortListener` cannot be hidden by another listener calling
+ * `stopImmediatePropagation`. Both branches return an explicit disposer so a
+ * completed operation does not remain attached to a long-lived caller signal.
+ */
+export function subscribeToAbort(signal, listener) {
+    if (typeof EventEmitter.addAbortListener === 'function') {
+        const subscription = EventEmitter.addAbortListener(signal, listener);
+        return () => subscription[Symbol.dispose]();
+    }
+    signal.addEventListener('abort', listener, { once: true });
+    return () => signal.removeEventListener('abort', listener);
+}
 export function createChildAbortController(parent) {
     const child = new AbortController();
     if (parent.signal.aborted) {

package/dist/utils/abort.js.map

@@ -1 +1 @@
-{"version":3,"file":"abort.js","sourceRoot":"","sources":["../../src/utils/abort.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,eAAe,CAAC,MAAe;IAC9C,IAAI,CAAC,CAAC,MAAM,YAAY,KAAK,CAAC;QAAE,OAAO,SAAS,CAAA;IAChD,uEAAuE;IACvE,wEAAwE;IACxE,oEAAoE;IACpE,mEAAmE;IACnE,EAAE;IACF,yEAAyE;IACzE,qEAAqE;IACrE,sEAAsE;IACtE,qCAAqC;IACrC,IACC,MAAM,CAAC,IAAI,KAAK,YAAY;QAC5B,MAAM,CAAC,IAAI,KAAK,cAAc;QAC9B,MAAM,CAAC,IAAI,KAAK,cAAc,EAC7B,CAAC;QACF,OAAO,SAAS,CAAA;IACjB,CAAC;IACD,MAAM,IAAI,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAA;IAC1C,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAA;AAC1C,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,MAAuB;IACjE,MAAM,KAAK,GAAG,IAAI,eAAe,EAAE,CAAA;IAEnC,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QAC3B,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QACjC,OAAO,KAAK,CAAA;IACb,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,OAAO,CAAC,KAAK,CAAC,CAAA;IAEpC,MAAM,aAAa,GAAG,GAAS,EAAE;QAChC,MAAM,GAAG,GAAG,SAAS,CAAC,KAAK,EAAE,CAAA;QAC7B,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YAChC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QAChC,CAAC;IACF,CAAC,CAAA;IAED,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;IAEtE,KAAK,CAAC,MAAM,CAAC,gBAAgB,CAC5B,OAAO,EACP,GAAG,EAAE;QACJ,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAA;IAC1D,CAAC,EACD,EAAE,IAAI,EAAE,IAAI,EAAE,CACd,CAAA;IAED,OAAO,KAAK,CAAA;AACb,CAAC"}
+{"version":3,"file":"abort.js","sourceRoot":"","sources":["../../src/utils/abort.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,eAAe,CAAC,MAAe;IAC9C,IAAI,CAAC,CAAC,MAAM,YAAY,KAAK,CAAC;QAAE,OAAO,SAAS,CAAA;IAChD,uEAAuE;IACvE,wEAAwE;IACxE,oEAAoE;IACpE,mEAAmE;IACnE,EAAE;IACF,yEAAyE;IACzE,qEAAqE;IACrE,sEAAsE;IACtE,qCAAqC;IACrC,IACC,MAAM,CAAC,IAAI,KAAK,YAAY;QAC5B,MAAM,CAAC,IAAI,KAAK,cAAc;QAC9B,MAAM,CAAC,IAAI,KAAK,cAAc,EAC7B,CAAC;QACF,OAAO,SAAS,CAAA;IACjB,CAAC;IACD,MAAM,IAAI,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAA;IAC1C,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAA;AAC1C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAmB,EAAE,QAAoB;IACzE,IAAI,OAAO,YAAY,CAAC,gBAAgB,KAAK,UAAU,EAAE,CAAC;QACzD,MAAM,YAAY,GAAG,YAAY,CAAC,gBAAgB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;QACpE,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAA;IAC5C,CAAC;IAED,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;IAC1D,OAAO,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;AAC3D,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,MAAuB;IACjE,MAAM,KAAK,GAAG,IAAI,eAAe,EAAE,CAAA;IAEnC,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QAC3B,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QACjC,OAAO,KAAK,CAAA;IACb,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,OAAO,CAAC,KAAK,CAAC,CAAA;IAEpC,MAAM,aAAa,GAAG,GAAS,EAAE;QAChC,MAAM,GAAG,GAAG,SAAS,CAAC,KAAK,EAAE,CAAA;QAC7B,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YAChC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QAChC,CAAC;IACF,CAAC,CAAA;IAED,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;IAEtE,KAAK,CAAC,MAAM,CAAC,gBAAgB,CAC5B,OAAO,EACP,GAAG,EAAE;QACJ,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAA;IAC1D,CAAC,EACD,EAAE,IAAI,EAAE,IAAI,EAAE,CACd,CAAA;IAED,OAAO,KAAK,CAAA;AACb,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namzu/sdk",
-  "version": "32.0.0",
+  "version": "33.1.0",
   "description": "Open-source AI agent SDK with a built-in runtime. Nothing between you and your agents.",
   "license": "FSL-1.1-MIT",
   "engines": {
@@ -77,11 +77,11 @@
     "lint": "biome check src/",
     "lint:fix": "biome check --write src/",
     "format": "biome format --write src/",
-    "test": "vitest run --passWithNoTests",
-    "test:coverage": "vitest run --passWithNoTests --coverage",
+    "test": "node ../../scripts/run-sdk-tests.mjs unit --passWithNoTests",
+    "test:coverage": "node ../../scripts/run-sdk-tests.mjs unit --passWithNoTests --coverage",
     "typecheck": "tsc --noEmit",
     "knip": "knip",
     "knip:production": "knip --production",
-    "test:proc": "tsc --build && vitest run --config vitest.proc.config.ts"
+    "test:proc": "tsc --build && node ../../scripts/run-sdk-tests.mjs proc"
   }
 }

package/src/authorization/gate.ts

@@ -21,7 +21,7 @@ export interface ToolCallContext {
  * What the rule actually said, in words a model can act on.
  *
  * This used to be the rule TYPE and nothing else, so a denial reached the
- * model as "Blocked by the verification gate: Matched rule: deny_by_name" —
+ * model as "Blocked by the authorization gate: Matched rule: deny_by_name" —
  * naming the kind of rule and nothing about it. Not which tool, not which
  * pattern, not whether a different input would fare better.
  *

package/src/bridge/a2a/mapper.ts

@@ -206,10 +206,29 @@ const MAPPING: {
 		}),
 
 	run_paused: (e, ctx) =>
-		statusEvent(e.runId, 'input-required', false, ctx, {
-			role: 'agent',
-			parts: [{ kind: 'text', text: `Run paused: ${e.reason}` }],
-		}),
+		statusEvent(
+			e.runId,
+			'input-required',
+			false,
+			ctx,
+			{
+				role: 'agent',
+				parts: [{ kind: 'text', text: `Run paused: ${e.reason}` }],
+			},
+			// A remote host has the same recovery decision as a local one. The
+			// checkpoint is the address of that recovery; the classification tells
+			// it whether and when a retry is justified.
+			{
+				checkpointId: e.checkpointId,
+				...(e.failure
+					? {
+							code: e.failure.code,
+							retryable: e.failure.retryable,
+							...(e.failure.details ? { details: e.failure.details } : {}),
+						}
+					: {}),
+			},
+		),
 
 	iteration_completed: null,
 	// Context management is kernel-internal bookkeeping; A2A peers model a

package/src/bridge/sse/mapper.ts

@@ -276,6 +276,9 @@ const MAPPING: {
 			run_id: runId,
 			checkpoint_id: e.checkpointId,
 			reason: e.reason,
+			...(e.failure ? { failure: e.failure } : {}),
+			...(e.providerError ? { provider_error: e.providerError } : {}),
+			...(e.explanation ? { explanation: e.explanation } : {}),
 		}),
 	},
 

package/src/connector/index.ts

@@ -24,9 +24,11 @@ export { WebhookConnector } from './builtins/webhook.js'
 // thing that defines one.
 export {
 	BaseExecutionContext,
+	CommandCancellationUnsupportedError,
 	ExecutionContextFactory,
 	HybridExecutionContext,
 	LocalExecutionContext,
+	RemoteExecutionBusyError,
 	RemoteExecutionContext,
 } from '../execution/index.js'
 export type {

package/src/connector/mcp/adapter.ts

@@ -1,14 +1,16 @@
 import { z } from 'zod'
 import { zodToJsonSchema } from 'zod-to-json-schema'
-import { wrapUntrusted } from '../../tools/untrusted-envelope.js'
+import { type UntrustedEnvelope, wrapUntrusted } from '../../tools/untrusted-envelope.js'
 import type {
 	MCPJsonSchema,
 	MCPToolDefinition,
 	MCPToolResult,
 } from '../../types/connector/index.js'
-import type { ToolResultBlock } from '../../types/message/index.js'
+import type { ToolResultBlock, ToolResultContent } from '../../types/message/index.js'
 import type { ToolContext, ToolDefinition, ToolResult } from '../../types/tool/index.js'
 import type { MCPClient } from './client.js'
+import { MCPHttpRedirectError } from './http-redirect.js'
+import { admitMcpImageBatch } from './image-admission.js'
 import { inlineSchemaRefs } from './schema-refs.js'
 
 /**
@@ -376,7 +378,9 @@ function positionalTypeName(member: unknown): string {
  * property collision the later member wins, matching the reading order.
  */
 function mergeAllOf(members: readonly unknown[], parent: Record<string, unknown>): JsonRecord {
-	const properties: JsonRecord = { ...((parent.properties as JsonRecord | undefined) ?? {}) }
+	const properties: JsonRecord = {
+		...((parent.properties as JsonRecord | undefined) ?? {}),
+	}
 	const required = new Set((parent.required as string[] | undefined) ?? [])
 	let additionalProperties = parent.additionalProperties
 
@@ -439,7 +443,9 @@ export function mcpToolToToolDefinition(
 		// Carried as the server wrote it. It is shown to the model, never
 		// validated here, so rebuilding it would only lose fidelity.
 		...(tool.outputSchema
-			? { outputSchema: inlineSchemaRefs(tool.outputSchema as unknown as Record<string, unknown>) }
+			? {
+					outputSchema: inlineSchemaRefs(tool.outputSchema as unknown as Record<string, unknown>),
+				}
 			: {}),
 		category: 'network',
 		permissions: ['network_access'],
@@ -453,10 +459,28 @@ export function mcpToolToToolDefinition(
 		provenance: { server: serverName, readOnlyHintTrusted },
 
 		async execute(input: unknown, context: ToolContext): Promise<ToolResult> {
-			const result = await client.callTool(tool.name, input as Record<string, unknown>, {
-				signal: context.abortSignal,
-			})
-			return frameServerResult(mcpToolResultToToolResult(result), serverName, tool.name)
+			try {
+				const result = await client.callTool(tool.name, input as Record<string, unknown>, {
+					signal: context.abortSignal,
+				})
+				return frameServerResult(mcpToolResultToToolResult(result), serverName, tool.name)
+			} catch (error) {
+				if (error instanceof MCPHttpRedirectError && error.remoteOutcomeUnknown) {
+					return {
+						success: false,
+						output: '',
+						error: error.message,
+						data: {
+							code: 'mcp_tool_outcome_unknown',
+							server: serverName,
+							tool: tool.name,
+							outcome: 'unknown',
+							retrySafety: 'unsafe',
+						},
+					}
+				}
+				throw error
+			}
 		},
 	}
 }
@@ -510,18 +534,31 @@ export function frameServerResult(
 	serverName: string,
 	toolName: string,
 ): ToolResult {
-	if (result.output.length === 0) return result
+	const envelope: UntrustedEnvelope = {
+		kind: 'connector-tool-result',
+		attributes: { server: serverName, tool: toolName },
+		provenance: 'This is output the named server returned, not this agent.',
+	}
+	const frameText = (text: string): string =>
+		text.length === 0 ? text : wrapUntrusted(envelope, text)
+	const frameContent = (content: ToolResultContent): ToolResultContent =>
+		typeof content === 'string'
+			? frameText(content)
+			: content.map((block) =>
+					block.type === 'text' ? { ...block, text: frameText(block.text) } : block,
+				)
+
+	const output = frameText(result.output)
+	const error = result.error === undefined ? undefined : frameText(result.error)
+	const content = result.content === undefined ? undefined : frameContent(result.content)
+	if (output === result.output && error === result.error && content === result.content)
+		return result
 
 	return {
 		...result,
-		output: wrapUntrusted(
-			{
-				kind: 'connector-tool-result',
-				attributes: { server: serverName, tool: toolName },
-				provenance: 'This is output the named server returned, not this agent.',
-			},
-			result.output,
-		),
+		output,
+		...(error !== undefined ? { error } : {}),
+		...(content !== undefined ? { content } : {}),
 	}
 }
 
@@ -530,6 +567,11 @@ export function mcpToolResultToToolResult(result: MCPToolResult): ToolResult {
 		.filter((block): block is { type: 'text'; text: string } => block.type === 'text')
 		.map((block) => block.text)
 		.join('\n')
+	const imageBlocks = result.content.filter(
+		(block): block is Extract<(typeof result.content)[number], { type: 'image' }> =>
+			block.type === 'image',
+	)
+	const imagesAdmitted = admitMcpImageBatch(imageBlocks)
 
 	// Non-text blocks used to be filtered out and never seen again: a
 	// bridged MCP server returning a chart, a screenshot or a PDF had that
@@ -540,8 +582,19 @@ export function mcpToolResultToToolResult(result: MCPToolResult): ToolResult {
 	for (const block of result.content) {
 		if (block.type === 'text') {
 			blocks.push({ type: 'text', text: block.text })
-		} else if (block.type === 'image' && block.data && block.mimeType) {
-			blocks.push({ type: 'image', data: block.data, mediaType: block.mimeType })
+		} else if (block.type === 'image') {
+			blocks.push({
+				type: 'image',
+				data: block.data,
+				mediaType: block.mimeType,
+				...(!imagesAdmitted
+					? {
+							modelOmission: {
+								reason: 'invalid-image' as const,
+							},
+						}
+					: {}),
+			})
 		} else if (block.type === 'resource' && block.resource?.text) {
 			// A resource with inline text is readable content; one that is
 			// only a URI is a pointer the model cannot dereference, so it is
@@ -556,10 +609,15 @@ export function mcpToolResultToToolResult(result: MCPToolResult): ToolResult {
 	// the model reading the answer and reading nothing at all — the call
 	// succeeded, so no error path would have caught it either. Text wins
 	// when both are present: the server wrote it for the model.
-	const output =
+	const visibleText =
 		textContent.length > 0 || result.structuredContent === undefined
 			? textContent
 			: stringifyStructured(result.structuredContent)
+	const invalidImageNotice =
+		imageBlocks.length > 0 && !imagesAdmitted
+			? '[MCP image batch withheld from model input: one or more blocks are not complete supported raster containers matching their declared media types.]'
+			: ''
+	const output = [visibleText, invalidImageNotice].filter((part) => part.length > 0).join('\n')
 
 	return {
 		success: !result.isError,
@@ -570,7 +628,10 @@ export function mcpToolResultToToolResult(result: MCPToolResult): ToolResult {
 		data:
 			result.structuredContent === undefined
 				? result.content
-				: { content: result.content, structuredContent: result.structuredContent },
+				: {
+						content: result.content,
+						structuredContent: result.structuredContent,
+					},
 		error: result.isError ? output : undefined,
 	}
 }

package/src/connector/mcp/client.ts

@@ -170,13 +170,14 @@ export class MCPClient {
 	async disconnect(): Promise<void> {
 		const reason = new Error('MCPClient disconnecting')
 		this.abortCancellations(reason)
-		if (this.status === 'disconnected') return
+		const alreadyDisconnected = this.status === 'disconnected'
 
 		this.rejectAllPending('MCPClient disconnecting')
 
 		await this.transport.close()
 		this.status = 'disconnected'
 		this.connectedAt = undefined
+		if (alreadyDisconnected) return
 		this.log.info('MCP client disconnected')
 		this.emitLifecycle({ type: 'mcp_client_disconnected', clientId: this.id })
 	}

package/src/connector/mcp/http-redirect.ts

@@ -0,0 +1,32 @@
+/**
+ * A request reached the configured MCP server, but no response from the
+ * requested operation was received because that server redirected it.
+ *
+ * This stays an internal transport-to-adapter signal. The public tool result
+ * carries the stable, serializable outcome fields instead of exposing an
+ * Error subclass as API.
+ */
+export class MCPHttpRedirectError extends Error {
+	readonly code = 'mcp_http_redirect_refused'
+	readonly remoteOutcomeUnknown: boolean
+
+	constructor(
+		readonly status: number,
+		readonly requestMethod?: string,
+	) {
+		const base = `MCP HTTP ${status} redirect was not followed because authenticated requests must remain at their configured endpoint. Configure the final MCP endpoint directly.`
+		const outcome =
+			requestMethod === 'tools/call'
+				? ' The configured MCP server received the tool call, so the remote outcome is unknown; do not automatically retry.'
+				: ''
+		super(base + outcome)
+		this.name = 'MCPHttpRedirectError'
+		this.remoteOutcomeUnknown = requestMethod === 'tools/call'
+	}
+}
+
+export function refuseMcpHttpRedirect(response: Response, requestMethod?: string): void {
+	if (response.status >= 300 && response.status < 400) {
+		throw new MCPHttpRedirectError(response.status, requestMethod)
+	}
+}

package/src/connector/mcp/http-sse.ts

@@ -7,6 +7,7 @@ import type {
 import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
 import { type Logger, resolveLogger } from '../../utils/logger.js'
 import { ConnectorHttpOperation, validateConnectorTimeoutMs } from '../http-operation.js'
+import { refuseMcpHttpRedirect } from './http-redirect.js'
 
 const DEFAULT_TIMEOUT_MS = 30_000
 
@@ -111,10 +112,12 @@ export class HttpSseTransport implements MCPTransport {
 						...this.config.headers,
 					},
 					body: JSON.stringify(message),
+					redirect: 'manual',
 					signal: operation.signal,
 				}),
 			)
 
+			refuseMcpHttpRedirect(response, message.method)
 			if (!response.ok) {
 				throw new Error(`HTTP ${response.status}: ${response.statusText}`)
 			}
@@ -202,9 +205,11 @@ export class HttpSseTransport implements MCPTransport {
 				Accept: 'text/event-stream',
 				...this.config.headers,
 			},
+			redirect: 'manual',
 			signal,
 		})
 
+		refuseMcpHttpRedirect(response)
 		if (!response.ok || !response.body) {
 			throw new Error(`SSE connection failed: HTTP ${response.status}`)
 		}

package/src/connector/mcp/image-admission.ts

@@ -0,0 +1,272 @@
+import type { MCPContentBlock } from '../../types/connector/index.js'
+
+const MAX_ENCODED_BYTES = 24 * 1024 * 1024
+const MAX_DIMENSION = 16_384
+const MAX_PIXELS = 40_000_000
+
+type MCPImageBlock = Extract<MCPContentBlock, { type: 'image' }>
+type ImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif'
+
+const IMAGE_MEDIA_TYPES = new Set<ImageMediaType>([
+	'image/png',
+	'image/jpeg',
+	'image/webp',
+	'image/gif',
+])
+
+function isImageMediaType(value: string): value is ImageMediaType {
+	return IMAGE_MEDIA_TYPES.has(value as ImageMediaType)
+}
+
+function decodeCanonicalBase64(value: string): Uint8Array | null {
+	if (value.length === 0 || value.length > MAX_ENCODED_BYTES) return null
+	if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
+		return null
+	}
+	const decoded = Buffer.from(value, 'base64')
+	return decoded.toString('base64') === value ? decoded : null
+}
+
+function dimensionsAreSafe(width: number, height: number): boolean {
+	return (
+		Number.isSafeInteger(width) &&
+		Number.isSafeInteger(height) &&
+		width > 0 &&
+		height > 0 &&
+		width <= MAX_DIMENSION &&
+		height <= MAX_DIMENSION &&
+		width * height <= MAX_PIXELS
+	)
+}
+
+const crcTable = (() => {
+	const table = new Uint32Array(256)
+	for (let n = 0; n < 256; n += 1) {
+		let value = n
+		for (let bit = 0; bit < 8; bit += 1) {
+			value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1
+		}
+		table[n] = value >>> 0
+	}
+	return table
+})()
+
+function crc32(bytes: Uint8Array, start: number, end: number): number {
+	let crc = 0xffffffff
+	for (let offset = start; offset < end; offset += 1) {
+		crc = (crcTable[(crc ^ (bytes[offset] ?? 0)) & 0xff] ?? 0) ^ (crc >>> 8)
+	}
+	return (crc ^ 0xffffffff) >>> 0
+}
+
+function isPng(bytes: Uint8Array): boolean {
+	const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+	if (bytes.length < 45 || !buffer.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex'))) {
+		return false
+	}
+	let offset = 8
+	let sawHeader = false
+	let sawData = false
+	while (offset + 12 <= bytes.length) {
+		const length = buffer.readUInt32BE(offset)
+		const typeStart = offset + 4
+		const dataStart = typeStart + 4
+		const dataEnd = dataStart + length
+		const chunkEnd = dataEnd + 4
+		if (dataEnd < dataStart || chunkEnd > bytes.length) return false
+		const type = buffer.toString('ascii', typeStart, dataStart)
+		if (buffer.readUInt32BE(dataEnd) !== crc32(bytes, typeStart, dataEnd)) return false
+		if (!sawHeader) {
+			if (type !== 'IHDR' || length !== 13) return false
+			const width = buffer.readUInt32BE(dataStart)
+			const height = buffer.readUInt32BE(dataStart + 4)
+			if (!dimensionsAreSafe(width, height)) return false
+			sawHeader = true
+		} else if (type === 'IHDR') return false
+		if (type === 'IDAT') sawData = true
+		if (type === 'IEND') return length === 0 && sawHeader && sawData && chunkEnd === bytes.length
+		offset = chunkEnd
+	}
+	return false
+}
+
+const JPEG_SOF_MARKERS = new Set([
+	0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf,
+])
+
+function isJpeg(bytes: Uint8Array): boolean {
+	const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+	if (bytes.length < 11 || bytes[0] !== 0xff || bytes[1] !== 0xd8) return false
+	let offset = 2
+	let sawFrame = false
+	let sawScan = false
+	let inScan = false
+	while (offset < bytes.length) {
+		if (inScan && bytes[offset] !== 0xff) {
+			offset += 1
+			continue
+		}
+		if (bytes[offset] !== 0xff) return false
+		while (offset < bytes.length && bytes[offset] === 0xff) offset += 1
+		if (offset >= bytes.length) return false
+		const marker = bytes[offset] ?? 0
+		offset += 1
+		if (inScan && (marker === 0x00 || (marker >= 0xd0 && marker <= 0xd7))) continue
+		inScan = false
+		if (marker === 0xd9) return sawFrame && sawScan && offset === bytes.length
+		if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) continue
+		if (offset + 2 > bytes.length) return false
+		const length = buffer.readUInt16BE(offset)
+		if (length < 2 || offset + length > bytes.length) return false
+		if (JPEG_SOF_MARKERS.has(marker)) {
+			if (length < 8) return false
+			const height = buffer.readUInt16BE(offset + 3)
+			const width = buffer.readUInt16BE(offset + 5)
+			if (!dimensionsAreSafe(width, height)) return false
+			sawFrame = true
+		}
+		offset += length
+		if (marker === 0xda) {
+			sawScan = true
+			inScan = true
+		}
+	}
+	return false
+}
+
+function skipGifSubBlocks(bytes: Uint8Array, start: number): number | null {
+	let offset = start
+	while (offset < bytes.length) {
+		const length = bytes[offset] ?? 0
+		offset += 1
+		if (length === 0) return offset
+		if (offset + length > bytes.length) return null
+		offset += length
+	}
+	return null
+}
+
+function isGif(bytes: Uint8Array): boolean {
+	const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+	if (bytes.length < 14) return false
+	const signature = buffer.toString('ascii', 0, 6)
+	if (signature !== 'GIF87a' && signature !== 'GIF89a') return false
+	if (!dimensionsAreSafe(buffer.readUInt16LE(6), buffer.readUInt16LE(8))) return false
+	let offset = 13
+	const packed = bytes[10] ?? 0
+	if ((packed & 0x80) !== 0) offset += 3 * 2 ** ((packed & 0x07) + 1)
+	if (offset > bytes.length) return false
+	let sawImage = false
+	while (offset < bytes.length) {
+		const marker = bytes[offset] ?? 0
+		offset += 1
+		if (marker === 0x3b) return sawImage && offset === bytes.length
+		if (marker === 0x21) {
+			if (offset >= bytes.length) return false
+			offset += 1
+			const next = skipGifSubBlocks(bytes, offset)
+			if (next === null) return false
+			offset = next
+			continue
+		}
+		if (marker !== 0x2c || offset + 9 > bytes.length) return false
+		const width = buffer.readUInt16LE(offset + 4)
+		const height = buffer.readUInt16LE(offset + 6)
+		if (!dimensionsAreSafe(width, height)) return false
+		const imagePacked = bytes[offset + 8] ?? 0
+		offset += 9
+		if ((imagePacked & 0x80) !== 0) offset += 3 * 2 ** ((imagePacked & 0x07) + 1)
+		if (offset >= bytes.length) return false
+		offset += 1
+		const next = skipGifSubBlocks(bytes, offset)
+		if (next === null) return false
+		offset = next
+		sawImage = true
+	}
+	return false
+}
+
+function readUInt24LE(bytes: Uint8Array, offset: number): number {
+	return (bytes[offset] ?? 0) | ((bytes[offset + 1] ?? 0) << 8) | ((bytes[offset + 2] ?? 0) << 16)
+}
+
+function webpDimensions(type: string, data: Uint8Array): readonly [number, number] | null {
+	const buffer = Buffer.from(data.buffer, data.byteOffset, data.byteLength)
+	if (type === 'VP8X') {
+		if (data.length < 10) return null
+		return [readUInt24LE(data, 4) + 1, readUInt24LE(data, 7) + 1]
+	}
+	if (type === 'VP8L') {
+		if (data.length < 5 || data[0] !== 0x2f) return null
+		const bits = buffer.readUInt32LE(1)
+		return [(bits & 0x3fff) + 1, ((bits >>> 14) & 0x3fff) + 1]
+	}
+	if (type === 'VP8 ') {
+		if (data.length < 10 || data[3] !== 0x9d || data[4] !== 0x01 || data[5] !== 0x2a) {
+			return null
+		}
+		return [buffer.readUInt16LE(6) & 0x3fff, buffer.readUInt16LE(8) & 0x3fff]
+	}
+	return null
+}
+
+function isWebp(bytes: Uint8Array): boolean {
+	const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+	if (
+		bytes.length < 20 ||
+		buffer.toString('ascii', 0, 4) !== 'RIFF' ||
+		buffer.readUInt32LE(4) + 8 !== bytes.length ||
+		buffer.toString('ascii', 8, 12) !== 'WEBP'
+	) {
+		return false
+	}
+	let offset = 12
+	let dimensions: readonly [number, number] | null = null
+	let sawImagePayload = false
+	while (offset + 8 <= bytes.length) {
+		const type = buffer.toString('ascii', offset, offset + 4)
+		const length = buffer.readUInt32LE(offset + 4)
+		const dataStart = offset + 8
+		const dataEnd = dataStart + length
+		if (dataEnd < dataStart || dataEnd > bytes.length) return false
+		const current = webpDimensions(type, bytes.subarray(dataStart, dataEnd))
+		if (current && dimensions === null) dimensions = current
+		if (type === 'VP8 ' || type === 'VP8L') sawImagePayload = current !== null
+		offset = dataEnd + (length & 1)
+	}
+	return (
+		offset === bytes.length &&
+		dimensions !== null &&
+		sawImagePayload &&
+		dimensionsAreSafe(dimensions[0], dimensions[1])
+	)
+}
+
+function imageIsAdmitted(block: MCPImageBlock): boolean {
+	if (!isImageMediaType(block.mimeType)) return false
+	const bytes = decodeCanonicalBase64(block.data)
+	if (!bytes) return false
+	switch (block.mimeType) {
+		case 'image/png':
+			return isPng(bytes)
+		case 'image/jpeg':
+			return isJpeg(bytes)
+		case 'image/gif':
+			return isGif(bytes)
+		case 'image/webp':
+			return isWebp(bytes)
+	}
+}
+
+/**
+ * Admit an MCP image batch atomically before any member becomes model input.
+ *
+ * A remote server controls the declared MIME and bytes. Canonical base64 is
+ * only an encoding property; the decoded value must also be a complete,
+ * bounded raster container whose format agrees with that declaration. One bad
+ * member withholds the complete batch so a model is never shown a partial
+ * result while the host retains every raw block for inspection.
+ */
+export function admitMcpImageBatch(images: readonly MCPImageBlock[]): boolean {
+	return images.length === 0 || images.every(imageIsAdmitted)
+}