@namzu/sdk 5.2.0 → 6.0.0

package/src/public-runtime.ts

@@ -78,6 +78,13 @@ export { modelVersionAtLeast, parseVersionedModelId } from './provider/model-ver
 // Strict tool input is a SUBSET of JSON Schema, and a keyword outside it makes
 // the vendor reject the whole request rather than degrade one field.
 export { assertStrictSchema, findStrictSchemaViolations } from './provider/strict-schema.js'
+// A tool has one schema; what changes per provider is the DIALECT the wire
+// parses, which is the wire's property. Rendered once, converted at the driver.
+export { findDraft07Only, toSchemaDialect } from './registry/tool/dialect.js'
+export type { JsonSchemaDialect } from './registry/tool/dialect.js'
+// The renderer itself, so a driver or a contract test can ask what a tool will
+// actually put on the wire without reaching into the registry.
+export { renderToolSchema } from './registry/tool/schema.js'
 export type { StrictSchemaViolation } from './provider/strict-schema.js'
 export type { ModelIdGrammar, ModelVersion } from './provider/model-version.js'
 export { drainQuery, query } from './runtime/query/index.js'

package/src/registry/tool/__tests__/dialect.test.ts

@@ -0,0 +1,197 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+
+import { findDraft07Only, toSchemaDialect } from '../dialect.js'
+import { renderToolSchema } from '../schema.js'
+
+/**
+ * The mechanism, tested in the kernel that owns it.
+ *
+ * The drivers each have their own test proving the conversion reaches their
+ * wire. This one is about the conversion itself: what it rewrites, what it
+ * deliberately leaves alone, and the two properties the prompt cache depends
+ * on — a stable reference and a frozen result.
+ */
+
+describe('saying a schema in the dialect a wire parses', () => {
+	it('moves a tuple from `items` to `prefixItems`', () => {
+		const draft07 = {
+			type: 'object',
+			properties: {
+				range: {
+					type: 'array',
+					items: [{ type: 'integer' }, { type: 'integer' }],
+					minItems: 2,
+					maxItems: 2,
+				},
+			},
+		}
+
+		expect(toSchemaDialect(draft07, '2020-12')).toEqual({
+			type: 'object',
+			properties: {
+				range: {
+					type: 'array',
+					prefixItems: [{ type: 'integer' }, { type: 'integer' }],
+					minItems: 2,
+					maxItems: 2,
+				},
+			},
+		})
+	})
+
+	it('leaves a homogeneous array alone, where `items` means the same thing', () => {
+		// The distinction the whole conversion turns on: `items` is only a
+		// tuple when it holds an ARRAY of schemas. One schema means "every
+		// element", which both dialects spell identically.
+		const schema = { type: 'array', items: { type: 'string' } }
+
+		expect(toSchemaDialect(schema, '2020-12')).toEqual(schema)
+	})
+
+	it('turns `additionalItems` into the 2020-12 `items`', () => {
+		// `additionalItems` only ever qualified an array-form `items` — it says
+		// what the elements AFTER the tuple look like. 2020-12 gave that job to
+		// `items` once `prefixItems` holds the positional schemas.
+		const converted = toSchemaDialect(
+			{
+				type: 'array',
+				items: [{ type: 'integer' }],
+				additionalItems: { type: 'string' },
+			},
+			'2020-12',
+		)
+
+		expect(converted).toEqual({
+			type: 'array',
+			prefixItems: [{ type: 'integer' }],
+			items: { type: 'string' },
+		})
+	})
+
+	it('drops `additionalItems: false`, which both dialects already imply', () => {
+		// Not a lossy shortcut: once `prefixItems` is set, a closed tuple is the
+		// default in 2020-12, so emitting `items: false` would add a byte to
+		// every request to say what was already true.
+		expect(
+			toSchemaDialect(
+				{ type: 'array', items: [{ type: 'integer' }], additionalItems: false },
+				'2020-12',
+			),
+		).toEqual({ type: 'array', prefixItems: [{ type: 'integer' }] })
+	})
+
+	it('ignores `additionalItems` with no tuple to qualify', () => {
+		// Meaningless in draft-07 too, so carrying it forward would be inventing
+		// a constraint the author did not write.
+		expect(
+			toSchemaDialect(
+				{ type: 'array', items: { type: 'string' }, additionalItems: { type: 'integer' } },
+				'2020-12',
+			),
+		).toEqual({ type: 'array', items: { type: 'string' } })
+	})
+
+	it('converts a tuple nested inside another tuple', () => {
+		const converted = toSchemaDialect(
+			{ type: 'array', items: [{ type: 'array', items: [{ type: 'integer' }] }] },
+			'2020-12',
+		) as Record<string, Record<string, unknown>[]>
+
+		expect(converted.prefixItems?.[0]).toEqual({
+			type: 'array',
+			prefixItems: [{ type: 'integer' }],
+		})
+	})
+
+	it('hands back the very same object for draft-07', () => {
+		// Not an equal object — the SAME one. The tools block sits at position 0
+		// of the prompt-cache prefix, so a driver that speaks draft-07 must not
+		// pay an allocation or risk a differently-ordered copy per request.
+		const schema = { type: 'object' }
+
+		expect(toSchemaDialect(schema, 'draft-07')).toBe(schema)
+	})
+
+	it('returns the same converted object every time it is asked', () => {
+		// Same reason. Conversion runs once per schema per dialect; a fresh
+		// object each iteration would invalidate the cache for the whole run
+		// even though the bytes were equal.
+		const schema = { type: 'array', items: [{ type: 'integer' }] }
+
+		expect(toSchemaDialect(schema, '2020-12')).toBe(toSchemaDialect(schema, '2020-12'))
+	})
+
+	it('freezes what it hands out, all the way down', () => {
+		// A caller that mutates a cached schema would poison every later render,
+		// and the symptom would be a silently invalidated prompt cache rather
+		// than an error. Freezing turns that into a throw at the mutation site.
+		const converted = toSchemaDialect(
+			{ type: 'object', properties: { a: { type: 'array', items: [{ type: 'integer' }] } } },
+			'2020-12',
+		) as { properties: { a: { prefixItems: unknown[] } } }
+
+		expect(Object.isFrozen(converted)).toBe(true)
+		expect(Object.isFrozen(converted.properties.a)).toBe(true)
+		expect(Object.isFrozen(converted.properties.a.prefixItems)).toBe(true)
+	})
+})
+
+describe('finding what a 2020-12 wire will refuse', () => {
+	it('names the path to an array-form `items`', () => {
+		expect(
+			findDraft07Only({
+				type: 'object',
+				properties: { range: { type: 'array', items: [{ type: 'integer' }] } },
+			}),
+		).toEqual(['properties.range.items'])
+	})
+
+	it('names `additionalItems` too', () => {
+		expect(findDraft07Only({ additionalItems: false })).toEqual(['additionalItems'])
+	})
+
+	it('walks into arrays, indexing the branch', () => {
+		expect(
+			findDraft07Only({
+				anyOf: [{ type: 'string' }, { type: 'array', items: [{ type: 'integer' }] }],
+			}),
+		).toEqual(['anyOf[1].items'])
+	})
+
+	it('does not descend into a tuple it has already reported', () => {
+		// Reporting the tuple and then each of its positional schemas would
+		// turn one fixable finding into a list nobody reads.
+		expect(
+			findDraft07Only({ type: 'array', items: [{ type: 'integer' }, { type: 'string' }] }),
+		).toEqual(['items'])
+	})
+
+	it('says nothing about a schema that is already 2020-12', () => {
+		expect(
+			findDraft07Only({
+				type: 'array',
+				prefixItems: [{ type: 'integer' }],
+				items: { type: 'string' },
+			}),
+		).toEqual([])
+	})
+
+	it('tolerates the leaves', () => {
+		expect(findDraft07Only(null)).toEqual([])
+		expect(findDraft07Only('a string')).toEqual([])
+		expect(findDraft07Only(42)).toEqual([])
+	})
+})
+
+describe('the round trip a real tool takes', () => {
+	it('renders a Zod tuple as draft-07 and converts it clean', () => {
+		// The actual defect, end to end: this is what `read.readRange` is.
+		const rendered = renderToolSchema(
+			z.object({ readRange: z.tuple([z.number(), z.number()]).optional() }),
+		)
+
+		expect(findDraft07Only(rendered)).not.toEqual([])
+		expect(findDraft07Only(toSchemaDialect(rendered, '2020-12'))).toEqual([])
+	})
+})

package/src/registry/tool/dialect.ts

@@ -0,0 +1,136 @@
+/**
+ * The dialect a wire speaks, and how to say the same schema in it.
+ *
+ * A tool has one Zod schema. What changes between providers is not the tool —
+ * it is the JSON Schema dialect the wire parses, which is a property of the
+ * wire. So the shape is rendered once, canonically, and each driver converts
+ * at the boundary where it knows which wire it is about to talk to.
+ *
+ * This exists because that layering was missing and it cost a production
+ * outage. `renderToolSchema` emits draft-07 (zod-to-json-schema's
+ * `jsonSchema7` target), every driver forwarded it verbatim, and one of the
+ * wires namzu speaks requires draft 2020-12. Measured against that live
+ * endpoint:
+ *
+ * | tool schema                    | result                                  |
+ * |--------------------------------|-----------------------------------------|
+ * | `items: [a, b]`   (draft-07)   | 400 — "must match JSON Schema draft 2020-12" |
+ * | `prefixItems: [a, b]` (2020-12)| accepted                                |
+ * | `items: { a }`                 | accepted                                |
+ *
+ * The failure is NOT about strict tool use. It fires with strict validation
+ * unset, and with it on the dialect error arrives *before* the strict-subset
+ * error — so a guard scoped to strict misses it entirely. One was, and did.
+ *
+ * Which wires want which dialect is the drivers' knowledge, not this file's:
+ * the vocabulary lives beside the wire that speaks it, and only the mechanism
+ * lives here.
+ *
+ * Only the conversions namzu can actually emit are implemented. The renderer
+ * runs with `$refStrategy: 'none'`, so there are no `$ref`/`definitions` to
+ * rewrite; a construct that cannot appear is not worth code that cannot be
+ * tested.
+ */
+
+/** Which spelling of JSON Schema a wire accepts. */
+export type JsonSchemaDialect = 'draft-07' | '2020-12'
+
+/**
+ * Rendered schemas are memoized and deeply frozen, so their identity is
+ * stable for the life of the tool — which makes them a sound `WeakMap` key.
+ *
+ * Converting per request would re-walk every tool's tree on every iteration,
+ * which is the waste `renderToolSchema`'s own cache exists to remove, and it
+ * would hand a fresh object to the wire each time. The tools block renders at
+ * position 0 of the prompt-cache prefix, so a differently-ordered but equal
+ * object still invalidates the cache for the whole run. Caching the conversion
+ * keeps the bytes identical across iterations.
+ */
+const CONVERTED = new Map<JsonSchemaDialect, WeakMap<object, Record<string, unknown>>>()
+
+/**
+ * Say this schema in the dialect the wire parses.
+ *
+ * Returns the input unchanged — same reference — when nothing needs saying
+ * differently, so the common case costs one map lookup and no allocation.
+ */
+export function toSchemaDialect(
+	schema: Record<string, unknown>,
+	dialect: JsonSchemaDialect,
+): Record<string, unknown> {
+	if (dialect === 'draft-07') return schema
+
+	let cache = CONVERTED.get(dialect)
+	if (!cache) {
+		cache = new WeakMap()
+		CONVERTED.set(dialect, cache)
+	}
+	const hit = cache.get(schema)
+	if (hit) return hit
+
+	const converted = to2020(schema) as Record<string, unknown>
+	const frozen = deepFreeze(converted)
+	cache.set(schema, frozen)
+	return frozen
+}
+
+/**
+ * Whether a schema still carries a construct the 2020-12 wire refuses.
+ *
+ * Exported so a test can sweep every shipped tool without reaching into the
+ * conversion, and so a driver can assert rather than hope.
+ */
+export function findDraft07Only(schema: unknown, path = ''): string[] {
+	if (Array.isArray(schema)) {
+		return schema.flatMap((item, i) => findDraft07Only(item, `${path}[${i}]`))
+	}
+	if (typeof schema !== 'object' || schema === null) return []
+
+	const node = schema as Record<string, unknown>
+	const found: string[] = []
+	// A tuple. In draft-07 the positional schemas live in `items`; 2020-12
+	// moved them to `prefixItems` and kept `items` for the rest, so the array
+	// form is not merely old — it means something else now, and the wire
+	// rejects the whole request rather than one field.
+	if (Array.isArray(node.items)) found.push(`${path ? `${path}.` : ''}items`)
+	// `additionalItems` only ever qualified an array-form `items`; 2020-12
+	// spells that `items`.
+	if ('additionalItems' in node) found.push(`${path ? `${path}.` : ''}additionalItems`)
+
+	for (const [key, value] of Object.entries(node)) {
+		if (key === 'items' && Array.isArray(value)) continue
+		found.push(...findDraft07Only(value, path ? `${path}.${key}` : key))
+	}
+	return found
+}
+
+function to2020(value: unknown): unknown {
+	if (Array.isArray(value)) return value.map(to2020)
+	if (typeof value !== 'object' || value === null) return value
+
+	const node = value as Record<string, unknown>
+	const out: Record<string, unknown> = {}
+	for (const [key, child] of Object.entries(node)) {
+		if (key === 'items' && Array.isArray(child)) {
+			out.prefixItems = child.map(to2020)
+			continue
+		}
+		if (key === 'additionalItems') {
+			// Only meaningful alongside an array-form `items`, where 2020-12
+			// calls the same thing `items`. `false` is the default in both
+			// dialects once `prefixItems` is set, so it carries nothing.
+			if (Array.isArray(node.items) && child !== false) out.items = to2020(child)
+			continue
+		}
+		out[key] = to2020(child)
+	}
+	return out
+}
+
+function deepFreeze<T>(value: T): T {
+	if (typeof value !== 'object' || value === null || Object.isFrozen(value)) return value
+	for (const key of Object.keys(value as Record<string, unknown>)) {
+		deepFreeze((value as Record<string, unknown>)[key])
+	}
+	return Object.freeze(value)
+}

package/src/registry/toolset/catalog.ts

@@ -1,4 +1,3 @@
-import { zodToJsonSchema } from 'zod-to-json-schema'
 import type { ToolRegistryContract } from '../../types/tool/index.js'
 import type { LLMToolSchema, ToolAvailability, ToolDefinition } from '../../types/tool/index.js'
 import type {
@@ -10,6 +9,7 @@ import type {
 	ToolsetDefinition,
 	ToolsetPolicy,
 } from '../../types/toolset/index.js'
+import { renderToolSchema } from '../tool/schema.js'
 
 export interface ToolCatalogSearchOptions {
 	readonly loading?: readonly ToolLoadingMode[]
@@ -245,12 +245,17 @@ function toolDefinitionToLLMTool(definition: ToolDefinition | undefined): LLMToo
 		function: {
 			name: definition.name,
 			description: definition.description,
+			// Through `renderToolSchema`, not a second inline conversion. The
+			// options were already identical, so this was not a different
+			// rendering — it was the same rendering without the guarantees:
+			// no `$schema` stripping (that key rides in the tools block, which
+			// sits at position 0 inside the prompt-cache prefix), no memoization,
+			// and no freeze. Two paths that agree today are two paths that can
+			// disagree tomorrow, and a tool reaching the wire through the catalog
+			// rather than the registry is not a different tool.
 			parameters:
 				(definition.modelInputSchema ? structuredClone(definition.modelInputSchema) : undefined) ??
-				(zodToJsonSchema(definition.inputSchema, {
-					target: 'jsonSchema7',
-					$refStrategy: 'none',
-				}) as Record<string, unknown>),
+				renderToolSchema(definition.inputSchema),
 		},
 	}
 }

package/src/runtime/query/__tests__/stream-recovery.test.ts

@@ -84,6 +84,7 @@ class ClassifiedFailureProvider implements LLMProvider {
 				providerId: 'classified-failure',
 				status: 429,
 				retryAfterMs: 2000,
+				detail: 'rate limit reached for this organization',
 			}),
 		)
 	}
@@ -210,11 +211,16 @@ describe('query stream recovery', () => {
 		)
 
 		expect(run.status).toBe('failed')
+		// `detail` rides along with the classification. Without it a host
+		// rendering this metadata knows a request was rejected but not why, and
+		// has to go re-parse the message string — which is the re-parsing this
+		// structured field exists to avoid.
 		expect(run.lastProviderError).toEqual({
 			kind: 'throttle',
 			providerId: 'classified-failure',
 			status: 429,
 			retryAfterMs: 2000,
+			detail: 'rate limit reached for this organization',
 		})
 		expect(events.find((event) => event.type === 'run_failed')).toMatchObject({
 			type: 'run_failed',

package/src/runtime/query/result.ts

@@ -129,6 +129,12 @@ export class ResultAssembler {
 					providerId: err.providerId,
 					...(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)

package/src/types/provider/error.ts

@@ -10,20 +10,36 @@ export type ProviderErrorKind =
 /**
  * Serializable provider-failure metadata carried by failed runs and events.
  *
- * No response body, vendor message, URL, or `cause` belongs here.
+ * No response body, URL, or `cause` belongs here. `detail` is the one thing
+ * the provider itself said, and it arrives scrubbed — see below.
  */
 export interface ProviderErrorInfo {
 	readonly kind: ProviderErrorKind
 	readonly providerId: string
 	readonly status?: number
 	readonly retryAfterMs?: number
+	/**
+	 * What the provider said was wrong, truncated and scrubbed of anything
+	 * credential-shaped.
+	 *
+	 * Carried here and not only on the error's `message` for the same reason
+	 * `kind` is: a host rendering a failure should not have to parse a
+	 * sentence to show one. It is the field that names the offending
+	 * parameter, which is usually the whole diagnosis.
+	 */
+	readonly detail?: string
 }
 
 export interface ProviderRequestErrorInit extends ProviderErrorInfo {
 	/**
-	 * Optional extra clause for the message. MUST be text this codebase
-	 * authored — never a fragment of a response body, a header, or a vendor
-	 * error.
+	 * Optional extra clause for the message.
+	 *
+	 * This used to be required to be text the codebase authored, never a
+	 * fragment of a vendor error — and the constructor did not read the field
+	 * at all, so nothing carried either kind of text. Providers may now pass
+	 * their own complaint through `vendorDetail`, which truncates it and
+	 * replaces anything credential-shaped. Text this codebase authored is
+	 * still welcome; what is not welcome is a raw body passed straight in.
 	 */
 	readonly detail?: string
 }