@namzu/sdk 6.2.0 → 8.0.0

package/src/connector/mcp/__tests__/positional-arrays.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect, it } from 'vitest'
+
+import { toSchemaDialect } from '../../../registry/tool/dialect.js'
+import { renderToolSchema } from '../../../registry/tool/schema.js'
+import type { MCPJsonSchema } from '../../../types/connector/index.js'
+import { mcpJsonSchemaToZod } from '../adapter.js'
+
+/**
+ * A bridged tool's schema makes a round trip — server JSON Schema → Zod →
+ * JSON Schema on the wire — so this file asserts what comes out the FAR end,
+ * not what the Zod type is. Two failures live at that far end and neither is
+ * visible from the Zod side:
+ *
+ *  - whatever the conversion drops is dropped from what the MODEL is shown,
+ *    and a positional array was being flattened to "an array of anything";
+ *  - whatever it emits has to be a construct the receiving wire accepts, and
+ *    a rejected tool schema fails the WHOLE request rather than degrading one
+ *    tool. So a faithful conversion that cannot be sent is worse than a lossy
+ *    one that can, which is why the tuple gate is narrow rather than eager.
+ */
+
+function wire(schema: MCPJsonSchema): Record<string, unknown> {
+	const rendered = renderToolSchema(mcpJsonSchemaToZod(schema))
+	const properties = toSchemaDialect(rendered, '2020-12').properties as Record<
+		string,
+		Record<string, unknown>
+	>
+	return properties.a as Record<string, unknown>
+}
+
+const wrap = (a: Record<string, unknown>): MCPJsonSchema =>
+	({ type: 'object', properties: { a }, required: ['a'] }) as unknown as MCPJsonSchema
+
+describe('a server that pinned its positions gets a tuple', () => {
+	it('carries the draft-07 spelling through to bounded prefixItems', () => {
+		expect(
+			wire(
+				wrap({
+					type: 'array',
+					items: [{ type: 'string' }, { type: 'number' }],
+					additionalItems: false,
+					minItems: 2,
+					maxItems: 2,
+				}),
+			),
+		).toEqual({
+			type: 'array',
+			minItems: 2,
+			maxItems: 2,
+			prefixItems: [{ type: 'string' }, { type: 'number' }],
+		})
+	})
+
+	it('reaches the identical wire shape from the 2020-12 spelling', () => {
+		// The two spellings say the same thing and a server may use either.
+		// Converging them is the point: a bridged tool should not be shown
+		// differently to the model because of which dialect its author wrote.
+		expect(
+			wire(
+				wrap({
+					type: 'array',
+					prefixItems: [{ type: 'string' }, { type: 'number' }],
+					items: false,
+					minItems: 2,
+				}),
+			),
+		).toEqual({
+			type: 'array',
+			minItems: 2,
+			maxItems: 2,
+			prefixItems: [{ type: 'string' }, { type: 'number' }],
+		})
+	})
+})
+
+describe('a positional array the wire cannot carry keeps its shape in words', () => {
+	it('falls back when the server did not pin the length', () => {
+		// The inversion worth pinning: positional members do NOT constrain
+		// length. With no `minItems` the server is permitting a SHORTER array,
+		// and a tuple cannot express that — so an absent lower bound is a
+		// reason to fall back rather than a detail to round up.
+		const result = wire(
+			wrap({
+				type: 'array',
+				prefixItems: [{ type: 'string' }, { type: 'number' }],
+			}),
+		)
+
+		expect(result.prefixItems).toBeUndefined()
+		expect(result.description).toContain('[0] string')
+		expect(result.description).toContain('[1] number')
+	})
+
+	it('appends the shape to the description rather than replacing it', () => {
+		// The case this exists for is a server that documented its argument
+		// WELL and used a positional array. Assigning the description would
+		// have deleted its sentence to make room for ours.
+		const result = wire(
+			wrap({
+				type: 'array',
+				prefixItems: [{ type: 'string' }, { type: 'number' }],
+				description: 'A coordinate pair.',
+			}),
+		)
+
+		expect(result.description).toContain('A coordinate pair.')
+		expect(result.description).toContain('[0] string')
+	})
+
+	it('keeps the bounds the server did state', () => {
+		// The fallback is a ZodArray precisely so the ordinary constraint pass
+		// still carries `minItems`/`maxItems` onto it.
+		const result = wire(
+			wrap({ type: 'array', prefixItems: [{ type: 'string' }], minItems: 1, maxItems: 9 }),
+		)
+
+		expect(result.minItems).toBe(1)
+		expect(result.maxItems).toBe(9)
+	})
+
+	it('names enums and literals in the description, not just types', () => {
+		const result = wire(
+			wrap({
+				type: 'array',
+				prefixItems: [{ enum: ['r', 'w'] }, { const: 7 }],
+			}),
+		)
+
+		expect(result.description).toContain('"r"|"w"')
+		expect(result.description).toContain('7')
+	})
+})
+
+describe('an ordinary list is untouched', () => {
+	it('still renders as a homogeneous array', () => {
+		expect(wire(wrap({ type: 'array', items: { type: 'string' } }))).toEqual({
+			type: 'array',
+			items: { type: 'string' },
+		})
+	})
+})
+
+describe('a deep schema cannot take the process down', () => {
+	// `MAX_CONVERSION_DEPTH` promised in its own comment that a node past the
+	// ceiling is "left permissive rather than the process being taken down by
+	// a stack overflow". That was false for arrays and for unions: the counter
+	// was never passed down the array path, and even where it WAS passed
+	// correctly — the union path — nothing compared it to anything, because
+	// the only comparison lived in the object branch a pure array or union
+	// never reaches. A remote server's tool listing is untrusted input, so
+	// this was reachable denial of service.
+	const nestArrays = (depth: number): MCPJsonSchema => {
+		let inner: Record<string, unknown> = { type: 'string' }
+		for (let i = 0; i < depth; i += 1) inner = { type: 'array', items: inner }
+		return wrap(inner)
+	}
+
+	const nestUnions = (depth: number): MCPJsonSchema => {
+		let inner: Record<string, unknown> = { type: 'string' }
+		for (let i = 0; i < depth; i += 1) inner = { anyOf: [inner] }
+		return wrap(inner)
+	}
+
+	it('survives a deeply nested array', () => {
+		expect(() => mcpJsonSchemaToZod(nestArrays(5_000))).not.toThrow()
+	})
+
+	it('survives a deeply nested union', () => {
+		expect(() => mcpJsonSchemaToZod(nestUnions(5_000))).not.toThrow()
+	})
+
+	it('still converts a shallow schema faithfully', () => {
+		// The guard must not be so eager that it flattens ordinary nesting.
+		const result = wire(
+			wrap({ type: 'array', items: { type: 'array', items: { type: 'number' } } }),
+		)
+
+		expect(result).toEqual({
+			type: 'array',
+			items: { type: 'array', items: { type: 'number' } },
+		})
+	})
+})

package/src/connector/mcp/adapter.ts

@@ -93,9 +93,20 @@ function jsonSchemaPropertyToZod(prop: unknown, depth = 0): z.ZodType {
 		base = base.nullable()
 	}
 
-	const description = schema.description
-	if (typeof description === 'string' && description.length > 0) {
-		base = base.describe(description)
+	// Appended, not assigned. The conversion itself can produce a description
+	// — a positional array that could not be expressed as a tuple carries its
+	// shape here, because that prose is the only place the model learns it —
+	// and `.describe()` REPLACES. Overwriting would have silently deleted the
+	// note in exactly the case it exists for: a server that documented its
+	// argument well AND used a positional array.
+	const carried = base.description
+	const declared = schema.description
+	const parts = [
+		typeof declared === 'string' && declared.length > 0 ? declared : undefined,
+		carried,
+	].filter((part): part is string => typeof part === 'string' && part.length > 0)
+	if (parts.length > 0) {
+		base = base.describe(parts.join(' '))
 	}
 
 	if (schema.default !== undefined) {
@@ -195,6 +206,12 @@ function baseTypeToZod(schema: Record<string, unknown>, depth = 0): z.ZodType {
 
 	const composite = (schema.anyOf ?? schema.oneOf) as unknown[] | undefined
 	if (Array.isArray(composite) && composite.length > 0) {
+		// The ceiling has to be CHECKED here, not merely counted. `depth` was
+		// threaded correctly through this branch from the start, and a
+		// 5000-deep union still overflowed the stack — because the only
+		// comparison against `MAX_CONVERSION_DEPTH` lived in `objectToZod`,
+		// which a pure union never reaches.
+		if (depth >= MAX_CONVERSION_DEPTH) return z.unknown()
 		const members = composite.map((member) => jsonSchemaPropertyToZod(member, depth + 1))
 		return members.length === 1
 			? (members[0] as z.ZodType)
@@ -229,11 +246,37 @@ function baseTypeToZod(schema: Record<string, unknown>, depth = 0): z.ZodType {
 		case 'null':
 			return z.null()
 		case 'array': {
+			// Both the counter and the check. `depth` was never passed to the
+			// element conversion below, so the counter reset to zero on every
+			// array level — and even threaded it would not have helped, since
+			// nothing on this path compared it to anything. Measured before
+			// and after: a 5000-deep array schema took the process down with a
+			// stack overflow, which is a denial of service reachable from a
+			// remote server's tool listing.
+			if (depth >= MAX_CONVERSION_DEPTH) return z.array(z.unknown())
+
+			// A positional array has two spellings and a server may use
+			// either: draft-07 puts the member schemas in `items` with the
+			// tail rule in `additionalItems`, 2020-12 moved them to
+			// `prefixItems` with the tail rule in `items`.
+			const positional = Array.isArray(schema.prefixItems)
+				? (schema.prefixItems as unknown[])
+				: Array.isArray(schema.items)
+					? (schema.items as unknown[])
+					: undefined
+			if (positional) return positionalToZod(positional, schema, depth)
+
 			const items = schema.items
-			// A tuple (`items` as an array) is rare in tool schemas; treat it
-			// as a heterogeneous list rather than pretending to model it.
-			if (Array.isArray(items)) return z.array(z.unknown())
-			return z.array(items === undefined ? z.unknown() : jsonSchemaPropertyToZod(items))
+			return z.array(
+				// A boolean `items` is a tail RULE, not an element schema — it
+				// only has meaning next to `prefixItems`, which was handled
+				// above. Reaching it here means the server closed an array
+				// that has no positions, and an unconstrained element type is
+				// the permissive reading of that.
+				items === undefined || typeof items === 'boolean'
+					? z.unknown()
+					: jsonSchemaPropertyToZod(items, depth + 1),
+			)
 		}
 		case 'object':
 			return objectToZod(schema, depth)
@@ -242,6 +285,87 @@ function baseTypeToZod(schema: Record<string, unknown>, depth = 0): z.ZodType {
 	}
 }
 
+/**
+ * How many positions we will express as a tuple.
+ *
+ * Not a correctness bound — a server may pin any arity it likes. It is a
+ * prompt-cost bound: every member renders its own schema into the tool
+ * definition the model is shown, and past a couple of dozen positions the
+ * thing being described is a data payload rather than a call signature. Past
+ * the cap the shape still reaches the model, in the description.
+ */
+const MAX_TUPLE_ARITY = 32
+
+/**
+ * A positional array: a tuple when the server pinned it, a described list
+ * otherwise.
+ *
+ * This used to be `z.array(z.unknown())` unconditionally, so a server that
+ * spelled out `[string, number]` had the model told "an array of anything" —
+ * the positions, their types and their order all dropped from what the model
+ * reads, not merely from what is validated locally.
+ *
+ * The reason it is not simply converted is that the schema makes a ROUND TRIP:
+ * server JSON Schema → Zod → JSON Schema on the wire. So whatever is emitted
+ * here has to be a construct the receiving wire accepts, and a construct it
+ * rejects fails the ENTIRE request rather than degrading one tool — taking
+ * 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.
+ *
+ * The subtlety worth stating, because it inverts the intuition: positional
+ * `items`/`prefixItems` does not constrain LENGTH. Without `minItems` the
+ * server is permitting a SHORTER array, and a tuple cannot express that — so
+ * an absent lower bound is a reason to fall back, not a detail to round up.
+ */
+function positionalToZod(
+	positional: readonly unknown[],
+	schema: Record<string, unknown>,
+	depth: number,
+): z.ZodType {
+	// draft-07 spells the tail rule `additionalItems`; 2020-12 spells it
+	// `items`, which is only a tail rule when `prefixItems` holds the members.
+	const tail = Array.isArray(schema.items) ? schema.additionalItems : schema.items
+
+	const arity = positional.length
+	const pinnedLow = num(schema.minItems) === arity
+	const closedHigh = tail === false || num(schema.maxItems) === arity
+
+	if (arity === 0 || arity > MAX_TUPLE_ARITY || !pinnedLow || !closedHigh) {
+		// A ZodArray, deliberately: `applyConstraints` then carries the
+		// server's own `minItems`/`maxItems` onto it, so the loose case keeps
+		// whatever bounds the server did state.
+		return z.array(z.unknown()).describe(describePositional(positional))
+	}
+
+	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[]])
+}
+
+/** The positional shape in prose, for the cases a tuple cannot carry. */
+function describePositional(positional: readonly unknown[]): string {
+	const shape = positional
+		.map((member, index) => `[${index}] ${positionalTypeName(member)}`)
+		.join(', ')
+	return `Positional array — ${shape}.`
+}
+
+function positionalTypeName(member: unknown): string {
+	if (typeof member !== 'object' || member === null) return 'any'
+	const schema = member as Record<string, unknown>
+	if (schema.const !== undefined) return JSON.stringify(schema.const)
+	if (Array.isArray(schema.enum)) return schema.enum.map((v) => JSON.stringify(v)).join('|')
+	const type = Array.isArray(schema.type) ? schema.type.join('|') : schema.type
+	return typeof type === 'string' ? type : 'any'
+}
+
 /**
  * Flatten `allOf` members into one object schema.
  *

package/src/constants/agent/index.ts

@@ -1,6 +1,11 @@
 import type { AgentCapabilities } from '../../types/agent/base.js'
 import type { AgentManagerConfig } from '../../types/agent/task.js'
 
+/**
+ * **Nothing reads this.** No activity list is trimmed to it anywhere.
+ *
+ * @deprecated Unused. Removed in the next major.
+ */
 export const MAX_RECENT_ACTIVITIES = 5
 
 export const AGENT_MANAGER_DEFAULTS: Readonly<AgentManagerConfig> = {

package/src/constants/plugin/index.ts

@@ -44,4 +44,19 @@ export const HOOK_TIMEOUT_MS = 5_000
  * can sort itself after.
  */
 export const DEFAULT_HOOK_PRIORITY = 100
+/**
+ * **Nothing reads this.** Hooks run sequentially and always have.
+ *
+ * It reads as a concurrency cap that is in force, which is the misleading
+ * kind of dead: a reviewer sees a bound, assumes hook execution is batched
+ * at ten, and reasons about plugin behaviour that does not exist.
+ *
+ * Kept for one release rather than deleted, because it is reachable from the
+ * published typings. Do not "make it work" by batching hook execution —
+ * ordering is the contract hooks are written against, and parallelising them
+ * to justify a constant would change behaviour to match a number nobody
+ * chose deliberately.
+ *
+ * @deprecated Unused. Removed in the next major.
+ */
 export const HOOK_MAX_CONCURRENT = 10

package/src/contracts/api.ts

@@ -155,6 +155,7 @@ export type StreamEventType =
 	 * transcript needs to know its middle was dropped, not infer it.
 	 */
 	| 'compaction.completed'
+	| 'compaction.failed'
 	/** A guardrail refused or corrected the run. */
 	| 'guardrail.triggered'
 	/**