@namzu/sdk 31.1.0 → 33.0.0

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)
+}

package/src/connector/mcp/stdio.ts

@@ -95,6 +95,10 @@ export class StdioTransport implements MCPTransport {
 	private closeHandlers: Array<() => void> = []
 	private errorHandlers: Array<(error: Error) => void> = []
 	private connected = false
+	/** The response channel ended for this process generation. */
+	private retired = false
+	/** Prevents a late event from an old child retiring its replacement. */
+	private generation = 0
 	/** True between kill and the process's own `close` event. */
 	private exitPending = false
 	private buffer = ''
@@ -109,38 +113,47 @@ export class StdioTransport implements MCPTransport {
 
 	async connect(): Promise<void> {
 		if (this.connected) return
+		// A protocol channel can end while its process stays alive. Reconnect
+		// must reap that old owner before publishing a new generation; otherwise
+		// both children remain live and teardown owns only the newest one.
+		if (this.process) await this.close()
+		const generation = ++this.generation
+		this.retired = false
+		this.buffer = ''
 
-		this.process = spawn(this.config.command, this.config.args ?? [], {
+		const child = spawn(this.config.command, this.config.args ?? [], {
 			env: buildChildEnv(this.config),
 			cwd: this.config.cwd,
 			stdio: ['pipe', 'pipe', 'pipe'],
 		})
+		this.process = child
 
-		this.process.stdout?.on('data', (chunk: Buffer) => {
+		child.stdout?.on('data', (chunk: Buffer) => {
+			if (generation !== this.generation || this.retired) return
 			this.buffer += chunk.toString('utf-8')
 			this.processBuffer()
 		})
+		child.stdout?.once('end', () => this.retire(generation, 'close'))
+		child.stdout?.once('close', () => this.retire(generation, 'close'))
+		child.stdout?.once('error', (err) => this.retire(generation, 'error', err))
 
-		this.process.stderr?.on('data', (chunk: Buffer) => {
+		child.stderr?.on('data', (chunk: Buffer) => {
 			this.log.warn('MCP server stderr', {
 				'namzu.mcp.stderr': chunk.toString('utf-8').trim(),
 			})
 		})
 
-		this.process.on('close', (code) => {
-			this.connected = false
-			this.log.info('MCP server process exited', { 'namzu.mcp.exit_code': code })
-			for (const handler of this.closeHandlers) handler()
-			// After the notification, not before it: this event is what tells
-			// `MCPClient` the session ended.
+		child.stdin?.once('close', () => this.retire(generation, 'close'))
+		child.stdin?.once('error', (err) => this.retire(generation, 'error', err))
+
+		child.on('close', (code) => {
+			if (this.process === child) this.process = null
 			this.exitPending = false
-			this.clearHandlers()
+			this.log.info('MCP server process exited', { 'namzu.mcp.exit_code': code })
+			this.retire(generation, 'close')
 		})
 
-		this.process.on('error', (err) => {
-			this.connected = false
-			for (const handler of this.errorHandlers) handler(err)
-		})
+		child.on('error', (err) => this.retire(generation, 'error', err))
 
 		this.connected = true
 		this.log.info('StdioTransport connected', {
@@ -175,7 +188,10 @@ export class StdioTransport implements MCPTransport {
 		// so both settle this, and two timers make a hang impossible: the
 		// first escalates to SIGKILL for a child ignoring SIGTERM, the second
 		// gives up waiting. Neither holds the event loop open.
-		if (child.pid === undefined) return
+		if (child.pid === undefined) {
+			this.exitPending = false
+			return
+		}
 		await new Promise<void>((resolve) => {
 			let settled = false
 			const finish = (): void => {
@@ -185,18 +201,20 @@ export class StdioTransport implements MCPTransport {
 				clearTimeout(giveUp)
 				resolve()
 			}
-			child.once('exit', finish)
+			child.once('close', finish)
 			child.once('error', finish)
-			child.kill('SIGTERM')
+			if (child.exitCode === null && child.signalCode === null) {
+				child.kill('SIGTERM')
+			}
 			const escalate = setTimeout(() => child.kill('SIGKILL'), TERMINATE_GRACE_MS)
 			const giveUp = setTimeout(finish, TERMINATE_GRACE_MS * 2)
 			escalate.unref?.()
 			giveUp.unref?.()
 		})
-		// The handlers deliberately survive this call. `process.on('close')`
-		// fires them when the process actually exits, and dropping them here
-		// would leave `MCPClient` believing it is still connected — so its next
-		// `connect()` would be refused with "already connected".
+		this.exitPending = false
+		// The active generation's terminal stream/process event owns handler
+		// retirement. A reconnect can register its handlers before `connect()`
+		// reaps an already-retired child, so `close()` must not clear them here.
 	}
 
 	/**
@@ -214,6 +232,30 @@ export class StdioTransport implements MCPTransport {
 		this.errorHandlers = []
 	}
 
+	/**
+	 * Publish one terminal result for the current response channel.
+	 *
+	 * A child may close stdout and keep running. That is just as terminal for
+	 * JSON-RPC as process exit: no pending or future request can receive a
+	 * response. Keeping the child handle is intentional; `close()` still owns
+	 * and reaps that process after the protocol session has been retired.
+	 */
+	private retire(generation: number, kind: 'close' | 'error', error?: Error): void {
+		if (generation !== this.generation || this.retired) return
+		this.retired = true
+		this.connected = false
+		this.buffer = ''
+		const closeHandlers = this.closeHandlers
+		const errorHandlers = this.errorHandlers
+		this.clearHandlers()
+		if (kind === 'error') {
+			const reason = error ?? new Error('MCP stdio transport failed')
+			for (const handler of errorHandlers) handler(reason)
+			return
+		}
+		for (const handler of closeHandlers) handler()
+	}
+
 	async send(message: MCPJsonRpcMessage, options?: MCPTransportSendOptions): Promise<void> {
 		options?.signal?.throwIfAborted()
 		if (!this.process?.stdin?.writable) {

package/src/connector/mcp/streamable-http.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
 
@@ -83,10 +84,12 @@ export class StreamableHttpTransport implements MCPTransport {
 					method: 'POST',
 					headers: this.buildHeaders(),
 					body: JSON.stringify(message),
+					redirect: 'manual',
 					signal: operation.signal,
 				}),
 			)
 
+			refuseMcpHttpRedirect(response, message.method)
 			if (!response.ok) {
 				throw new Error(`StreamableHttpTransport: HTTP ${response.status}: ${response.statusText}`)
 			}

package/src/constants/tools/index.ts

@@ -1,4 +1,4 @@
-// Patterns the verification gate's `deny_dangerous_patterns` rule
+// Patterns the authorization gate's `deny_dangerous_patterns` rule
 // matches against the JSON-serialised tool input. The list is
 // intentionally short and high-signal: the goal is to catch the
 // canonical "I will brick the host" mistakes (filesystem wipes,

package/src/directory/derive-supervisor.ts

@@ -143,6 +143,11 @@ export function deriveSupervisorOptions(
 					maxRequestRichContentBytes: manifest.config.maxRequestRichContentBytes,
 				}
 			: {}),
+		...(manifest.config.attachmentResolveTimeoutMs !== undefined
+			? {
+					attachmentResolveTimeoutMs: manifest.config.attachmentResolveTimeoutMs,
+				}
+			: {}),
 		...(manifest.config.temperature !== undefined
 			? { temperature: manifest.config.temperature }
 			: {}),

package/src/directory/derive.ts

@@ -72,6 +72,11 @@ export function deriveRunOptions(
 					maxRequestRichContentBytes: manifest.config.maxRequestRichContentBytes,
 				}
 			: {}),
+		...(manifest.config.attachmentResolveTimeoutMs !== undefined
+			? {
+					attachmentResolveTimeoutMs: manifest.config.attachmentResolveTimeoutMs,
+				}
+			: {}),
 		...(input.identity ?? {}),
 		...(input.overrides ?? {}),
 	}

package/src/directory/load.ts

@@ -187,6 +187,7 @@ function readConfig(
 	take('timeoutMs', isNumber, 'finite number')
 	take('streamIdleTimeoutMs', isNumber, 'finite number')
 	take('maxRequestRichContentBytes', isNumber, 'finite number')
+	take('attachmentResolveTimeoutMs', isNumber, 'finite number')
 
 	// `metadata` is typed `Record<string, string>` and was admitted on
 	// `typeof === 'object'` alone — which an array also satisfies, and which

package/src/directory/types.ts

@@ -170,6 +170,8 @@ export interface DirectoryConfig {
 	readonly streamIdleTimeoutMs?: number
 	/** Accumulated inline image/document bytes per provider request; `0` disables. */
 	readonly maxRequestRichContentBytes?: number
+	/** Maximum stored-attachment materialization time; `0` disables the bound. */
+	readonly attachmentResolveTimeoutMs?: number
 	/** Names the agent in traces and events when declared. */
 	readonly name?: string
 	/** Free-form labels for an inspector. Never interpreted by this package. */