@namzu/sdk 39.0.0 → 41.0.0

package/src/connector/mcp/adapter.ts

@@ -9,7 +9,9 @@ import type {
 } from '../../types/connector/index.js'
 import type { ToolResultBlock, ToolResultContent } from '../../types/message/index.js'
 import type { ToolContext, ToolDefinition, ToolResult } from '../../types/tool/index.js'
+import { admitMcpAudioBatch } from './audio-admission.js'
 import type { MCPClient } from './client.js'
+import { MCPInputRequiredError, isMissingRequiredClientCapabilityError } from './errors.js'
 import { MCPHttpRedirectError } from './http-redirect.js'
 import { admitMcpImageBatch } from './image-admission.js'
 
@@ -338,11 +340,20 @@ const MAX_TUPLE_ARITY = 32
  * down every run that offered the toolset. A faithful conversion that cannot
  * be sent is strictly worse than a lossy one that can.
  *
- * Hence the narrow gate. A tuple is emitted only where the server itself
- * pinned the arity and closed the tail, because that renders as bounded
- * `prefixItems` — the one positional shape measured as accepted, and the same
- * shape a first-party builtin already ships. Everything else keeps the
- * permissive array and gains the positional shape in its description.
+ * NO positional shape is a construct every wire accepts. That was measured the
+ * expensive way: `items: [a, b]` is refused by a wire validating against JSON
+ * Schema 2020-12, `prefixItems: [a, b]` is unknown to a draft-07 one — which
+ * DROPS it silently rather than complaining — and only three of the ten
+ * drivers convert between them. So the rendering boundary now collapses every
+ * tuple to a uniform array (`registry/tool/portable.ts`), and this function's
+ * job changed with it: the tuple it returns is the PARSER, which still refuses
+ * a wrongly-typed or wrongly-ordered call, while the positions reach the model
+ * as prose in the description — the one channel every wire carries intact.
+ *
+ * Hence the narrow gate, which still matters: a tuple is a parser strict
+ * enough to reject a shorter array, so it is built only where the server
+ * itself pinned the arity and closed the tail. Everything else keeps the
+ * permissive array. Either way the positional shape is described.
  *
  * The subtlety worth stating, because it inverts the intuition: positional
  * `items`/`prefixItems` does not constrain LENGTH. Without `minItems` the
@@ -372,7 +383,12 @@ function positionalToZod(
 	const members = positional.map((member) => jsonSchemaPropertyToZod(member, depth + 1))
 	// Never `.rest()`. It renders a tail schema this wire has not been measured
 	// against, and the gate above has already established there is no tail.
-	return z.tuple(members as [z.ZodType, ...z.ZodType[]])
+	//
+	// Described as well as parsed: the rendering collapses the tuple to a
+	// uniform array, so without this sentence the model would be shown "two of
+	// string-or-number" for a schema the parser reads as "a string then a
+	// number" — and would learn the difference only from a rejected call.
+	return z.tuple(members as [z.ZodType, ...z.ZodType[]]).describe(describePositional(positional))
 }
 
 /** The positional shape in prose, for the cases a tuple cannot carry. */
@@ -502,12 +518,68 @@ export function mcpToolToToolDefinition(
 						},
 					}
 				}
+				// MRTR: a conforming server never sends this, since namzu declares
+				// `clientCapabilities: {}` — but a non-conforming one, or a second
+				// `input_required` after the one automatic retry `MCPClient`
+				// already made, is named here rather than reaching the caller as
+				// an unexplained rejection. No side effect is known to have
+				// happened on this path (the spec's model is that a call ending
+				// in `input_required` has not truly run yet), so a retry — of
+				// this tool, or a different approach entirely — is safe.
+				if (error instanceof MCPInputRequiredError) {
+					const requested = error.inputRequests.map((request) => request.method)
+					return frameServerResult(
+						{
+							success: false,
+							output: '',
+							error: `MCP tool "${tool.name}" on server "${serverName}" asked for input this client has no way to supply${requested.length > 0 ? ` (${requested.join(', ')})` : ''}.`,
+							data: {
+								code: 'mcp_tool_input_required',
+								server: serverName,
+								tool: tool.name,
+								requested,
+								retrySafety: 'safe',
+							},
+						},
+						serverName,
+						tool.name,
+					)
+				}
+				// Same principle, for the other outcome a no-capability host is
+				// genuinely likely to see: the server refused before running the
+				// tool because this client never declared a capability it needs.
+				if (isMissingRequiredClientCapabilityError(error)) {
+					const requiredCapabilities = requiredCapabilitiesFrom(error.data)
+					return frameServerResult(
+						{
+							success: false,
+							output: '',
+							error: `MCP tool "${tool.name}" on server "${serverName}" requires client capabilities this client did not declare${requiredCapabilities.length > 0 ? ` (${requiredCapabilities.join(', ')})` : ''}.`,
+							data: {
+								code: 'mcp_tool_missing_client_capability',
+								server: serverName,
+								tool: tool.name,
+								requiredCapabilities,
+								retrySafety: 'safe',
+							},
+						},
+						serverName,
+						tool.name,
+					)
+				}
 				throw error
 			}
 		},
 	}
 }
 
+/** Read `-32021`'s `data.requiredCapabilities` defensively — it is a server's own claim, not a validated shape. */
+function requiredCapabilitiesFrom(data: unknown): string[] {
+	if (typeof data !== 'object' || data === null) return []
+	const required = (data as { requiredCapabilities?: unknown }).requiredCapabilities
+	return Array.isArray(required) ? required.filter((c): c is string => typeof c === 'string') : []
+}
+
 export function toolDefinitionToMCPTool(tool: ToolDefinition): MCPToolDefinition {
 	return {
 		name: tool.name,
@@ -595,6 +667,11 @@ export function mcpToolResultToToolResult(result: MCPToolResult): ToolResult {
 			block.type === 'image',
 	)
 	const imagesAdmitted = admitMcpImageBatch(imageBlocks)
+	const audioBlocks = result.content.filter(
+		(block): block is Extract<(typeof result.content)[number], { type: 'audio' }> =>
+			block.type === 'audio',
+	)
+	const audiosAdmitted = admitMcpAudioBatch(audioBlocks)
 
 	// 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
@@ -603,6 +680,13 @@ export function mcpToolResultToToolResult(result: MCPToolResult): ToolResult {
 	// as model-visible content when any are present.
 	const blocks: ToolResultBlock[] = []
 	const pins: WorkingStatePin[] = []
+	// Set only by a block type that has no `ToolResultBlock` shape of its
+	// own and is rendered as a plain text pointer instead (`resource_link`
+	// today). Without this, a result made up entirely of such pointers
+	// would compute `hasRichContent` false — every pushed block LOOKS like
+	// ordinary text — and the whole `content` array, the pointer's only
+	// carrier, would be dropped by the `hasRichContent` gate below.
+	let hasNamedPointer = false
 	for (const block of result.content) {
 		if (block.type === 'resource' && block.resource?.mimeType === WORKING_STATE_MIME) {
 			// A server pins facts by returning them as a resource of this type:
@@ -626,14 +710,31 @@ export function mcpToolResultToToolResult(result: MCPToolResult): ToolResult {
 						}
 					: {}),
 			})
+		} else if (block.type === 'resource_link') {
+			// A resource_link never carries content, admitted or not — it is
+			// a pointer the model cannot dereference, so it is named rather
+			// than pretended to be present, exactly like a URI-only embedded
+			// resource just below.
+			blocks.push({
+				type: 'text',
+				text: `[MCP resource link: ${block.name} (${block.uri})]`,
+			})
+			hasNamedPointer = true
 		} 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
-			// named rather than pretended to be present.
+			// only a URI, or only a `blob`, is a pointer the model cannot
+			// dereference, so it is named rather than pretended to be
+			// present — here, that means it is left out of `blocks`
+			// entirely rather than rendered as fabricated text.
 			blocks.push({ type: 'text', text: block.resource.text })
 		}
+		// `audio` has no `ToolResultBlock` shape of its own today, so it is
+		// summarized into `output` below rather than pushed here — the
+		// same reasoning that keeps a withheld image out of plain text,
+		// applied to a media type this adapter cannot pass through as
+		// bytes at all yet.
 	}
-	const hasRichContent = blocks.some((b) => b.type !== 'text')
+	const hasRichContent = hasNamedPointer || blocks.some((b) => b.type !== 'text')
 
 	// A server may answer with a structured payload and skip the
 	// compatibility text block. Serializing it is the difference between
@@ -648,7 +749,19 @@ export function mcpToolResultToToolResult(result: MCPToolResult): ToolResult {
 		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')
+	// Audio has no `ToolResultBlock` carrier, so an admitted clip is named
+	// in `output` by its media type instead of being dumped into `content`
+	// as base64 text — the same mistake this adapter already fixed once for
+	// screenshots. A withheld batch gets the same notice shape as images.
+	const audioNotice =
+		audioBlocks.length === 0
+			? ''
+			: audiosAdmitted
+				? `[MCP audio: ${audioBlocks.map((block) => block.mimeType).join(', ')}]`
+				: '[MCP audio batch withheld from model input: one or more blocks are not complete supported audio containers matching their declared media types.]'
+	const output = [visibleText, invalidImageNotice, audioNotice]
+		.filter((part) => part.length > 0)
+		.join('\n')
 
 	return {
 		...(pins.length > 0 ? { workingState: pins } : {}),

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

@@ -0,0 +1,173 @@
+import type { MCPContentBlock } from '../../types/connector/index.js'
+
+const MAX_ENCODED_BYTES = 24 * 1024 * 1024
+
+type MCPAudioBlock = Extract<MCPContentBlock, { type: 'audio' }>
+type AudioMediaType = 'audio/wav' | 'audio/mpeg' | 'audio/ogg'
+
+const AUDIO_MEDIA_TYPES = new Set<AudioMediaType>(['audio/wav', 'audio/mpeg', 'audio/ogg'])
+
+function isAudioMediaType(value: string): value is AudioMediaType {
+	return AUDIO_MEDIA_TYPES.has(value as AudioMediaType)
+}
+
+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
+}
+
+/**
+ * A canonical RIFF/WAVE container: the size field agrees with the buffer
+ * length, and walking its chunks (word-aligned, as RIFF requires) lands
+ * exactly on the end of the buffer having seen both a `fmt ` and a `data`
+ * chunk. Mirrors the WebP walker in `image-admission.ts`, which is the same
+ * RIFF container format wearing a different fourCC.
+ */
+function isWav(bytes: Uint8Array): boolean {
+	const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+	if (
+		bytes.length < 12 ||
+		buffer.toString('ascii', 0, 4) !== 'RIFF' ||
+		buffer.readUInt32LE(4) + 8 !== bytes.length ||
+		buffer.toString('ascii', 8, 12) !== 'WAVE'
+	) {
+		return false
+	}
+	let offset = 12
+	let sawFmt = false
+	let sawData = false
+	while (offset + 8 <= bytes.length) {
+		const chunkId = buffer.toString('ascii', offset, offset + 4)
+		const chunkSize = buffer.readUInt32LE(offset + 4)
+		const dataStart = offset + 8
+		const dataEnd = dataStart + chunkSize
+		if (dataEnd < dataStart || dataEnd > bytes.length) return false
+		if (chunkId === 'fmt ') {
+			if (chunkSize < 16) return false
+			sawFmt = true
+		}
+		if (chunkId === 'data') sawData = true
+		// RIFF chunks are padded to an even byte count; the pad byte is not
+		// counted in chunkSize but is present in the stream.
+		offset = dataEnd + (chunkSize % 2)
+	}
+	return sawFmt && sawData && offset === bytes.length
+}
+
+/**
+ * A sequence of Ogg pages, each framed by its `OggS` capture pattern and a
+ * segment table whose declared sizes account for every byte of payload.
+ * Page checksums are not verified — the framing itself, consumed exactly to
+ * the end of the buffer, is what this admits or refuses.
+ */
+function isOgg(bytes: Uint8Array): boolean {
+	const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+	let offset = 0
+	let sawPage = false
+	while (offset + 27 <= bytes.length) {
+		if (buffer.toString('ascii', offset, offset + 4) !== 'OggS') return false
+		if (bytes[offset + 4] !== 0) return false // stream_structure_version
+		const segmentCount = bytes[offset + 26] ?? 0
+		const segmentTableStart = offset + 27
+		if (segmentTableStart + segmentCount > bytes.length) return false
+		let payloadLength = 0
+		for (let i = 0; i < segmentCount; i += 1) {
+			payloadLength += bytes[segmentTableStart + i] ?? 0
+		}
+		const payloadEnd = segmentTableStart + segmentCount + payloadLength
+		if (payloadEnd > bytes.length) return false
+		sawPage = true
+		offset = payloadEnd
+	}
+	return sawPage && offset === bytes.length
+}
+
+// MPEG-1 Layer III bitrates in kbps, indexed by the header's 4-bit field.
+// Index 0 (free bitrate) and 15 (reserved) are both treated as unsupported.
+const MPEG1_L3_BITRATES: readonly number[] = [
+	0, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 0,
+]
+const MPEG1_SAMPLE_RATES: readonly number[] = [44100, 48000, 32000, 0]
+
+/** Frame length in bytes for an MPEG-1 Layer III frame, or null if the header is malformed/unsupported. */
+function mp3FrameLength(headerByte1: number, headerByte2: number): number | null {
+	const versionBits = (headerByte1 >> 3) & 0x3
+	const layerBits = (headerByte1 >> 1) & 0x3
+	if (versionBits !== 0x3 || layerBits !== 0x1) return null // MPEG-1, Layer III only
+	const bitrateIndex = (headerByte2 >> 4) & 0xf
+	const sampleRateIndex = (headerByte2 >> 2) & 0x3
+	const padding = (headerByte2 >> 1) & 0x1
+	if (bitrateIndex === 0 || bitrateIndex === 0xf || sampleRateIndex === 0x3) return null
+	const bitrate = MPEG1_L3_BITRATES[bitrateIndex]
+	const sampleRate = MPEG1_SAMPLE_RATES[sampleRateIndex]
+	if (!bitrate || !sampleRate) return null
+	return Math.floor((144 * bitrate * 1000) / sampleRate) + padding
+}
+
+function id3v2TagLength(bytes: Uint8Array, buffer: Buffer): number {
+	if (bytes.length < 10 || buffer.toString('ascii', 0, 3) !== 'ID3') return 0
+	// Synchsafe integer: 7 significant bits per byte, big-endian.
+	const size =
+		((bytes[6] ?? 0) & 0x7f) * 0x200000 +
+		((bytes[7] ?? 0) & 0x7f) * 0x4000 +
+		((bytes[8] ?? 0) & 0x7f) * 0x80 +
+		((bytes[9] ?? 0) & 0x7f)
+	return 10 + size
+}
+
+/**
+ * MPEG-1 Layer III frames, one after another with no trailing bytes: an
+ * optional ID3v2 tag is skipped, then every remaining byte must belong to a
+ * syntactically valid frame header whose declared length reaches exactly
+ * the next frame (or the end of the buffer). Other MPEG versions and layers
+ * are refused rather than approximated.
+ */
+function isMp3(bytes: Uint8Array): boolean {
+	const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+	const offsetAfterTag = id3v2TagLength(bytes, buffer)
+	if (offsetAfterTag + 4 > bytes.length) return false
+	let offset = offsetAfterTag
+	let sawFrame = false
+	while (offset + 4 <= bytes.length) {
+		if (bytes[offset] !== 0xff || ((bytes[offset + 1] ?? 0) & 0xe0) !== 0xe0) return false
+		const frameLength = mp3FrameLength(bytes[offset + 1] ?? 0, bytes[offset + 2] ?? 0)
+		if (frameLength === null || frameLength < 4 || offset + frameLength > bytes.length) {
+			return false
+		}
+		sawFrame = true
+		offset += frameLength
+	}
+	return sawFrame && offset === bytes.length
+}
+
+function audioIsAdmitted(block: MCPAudioBlock): boolean {
+	if (!isAudioMediaType(block.mimeType)) return false
+	const bytes = decodeCanonicalBase64(block.data)
+	if (!bytes) return false
+	switch (block.mimeType) {
+		case 'audio/wav':
+			return isWav(bytes)
+		case 'audio/ogg':
+			return isOgg(bytes)
+		case 'audio/mpeg':
+			return isMp3(bytes)
+	}
+}
+
+/**
+ * Admit an MCP audio batch atomically before any member becomes model input.
+ *
+ * Mirrors `admitMcpImageBatch`: a remote server controls the declared MIME
+ * and bytes, canonical base64 is only an encoding property, and the decoded
+ * value must also be a complete, bounded container whose framing agrees
+ * with the declared media type. 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 admitMcpAudioBatch(audios: readonly MCPAudioBlock[]): boolean {
+	return audios.length === 0 || audios.every(audioIsAdmitted)
+}