@namzu/sdk 5.2.0 → 6.1.0

package/src/provider/__tests__/vendor-detail.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'vitest'
+
+import { providerHttpError, redactSecrets, vendorDetail } from '../errors.js'
+
+/**
+ * The provider's own account of what was wrong, kept — and scrubbed.
+ *
+ * `ProviderRequestErrorInit` declared `detail` from the beginning and the
+ * constructor never read it, so the field existed and carried nothing. The
+ * body was read to classify and then dropped, deliberately, because an error
+ * body can echo a request and a request can carry a key.
+ *
+ * The cost of that trade showed up in production: the wire had been saying
+ * `tools.0.custom.input_schema: … must match JSON Schema draft 2020-12` and
+ * the SDK deleted the sentence, so diagnosing it took seven eliminated
+ * hypotheses and a day of downtime. Keeping the sentence and scrubbing the
+ * credential shapes is the trade that was actually available.
+ */
+
+describe('the sentence that names the broken field survives', () => {
+	it('lifts the structured message out of a vendor body', () => {
+		const body = JSON.stringify({
+			type: 'error',
+			error: {
+				type: 'invalid_request_error',
+				message:
+					'tools.0.custom.input_schema: JSON schema is invalid. It must match JSON Schema draft 2020-12',
+			},
+		})
+
+		expect(vendorDetail(body)).toBe(
+			'tools.0.custom.input_schema: JSON schema is invalid. It must match JSON Schema draft 2020-12',
+		)
+	})
+
+	it('reaches the error a caller actually catches', () => {
+		const err = providerHttpError({
+			providerId: 'anthropic',
+			status: 400,
+			body: JSON.stringify({ error: { message: "Schema type 'oneOf' is not supported" } }),
+		})
+
+		expect(err.detail).toContain('oneOf')
+		// …and the message too, so a log line that prints only the message is
+		// still enough to act on.
+		expect(err.message).toContain('oneOf')
+	})
+
+	it('falls back to the raw text when the body is not JSON', () => {
+		expect(vendorDetail('upstream connect error, transport failure')).toBe(
+			'upstream connect error, transport failure',
+		)
+	})
+
+	it('says nothing rather than something empty', () => {
+		expect(vendorDetail(undefined)).toBeUndefined()
+		expect(vendorDetail(null)).toBeUndefined()
+		expect(vendorDetail('   ')).toBeUndefined()
+		expect(vendorDetail({})).toBeUndefined()
+	})
+
+	it('truncates a body that is not a sentence', () => {
+		const detail = vendorDetail('x'.repeat(5_000))
+		expect(detail?.length).toBeLessThanOrEqual(401)
+		expect(detail?.endsWith('…')).toBe(true)
+	})
+})
+
+describe('a credential never rides along', () => {
+	it.each([
+		['sk-ant-api03-AbCdEfGhIjKlMnOpQrStUv', 'anthropic-style key'],
+		['npm_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345', 'npm token'],
+		['ghp_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345', 'github token'],
+		['AKIAIOSFODNN7EXAMPLE', 'aws access key id'],
+	])('scrubs %s (%s)', (secret) => {
+		const scrubbed = redactSecrets(`upstream rejected token ${secret} for this request`)
+		expect(scrubbed).not.toContain(secret)
+		expect(scrubbed).toContain('[redacted]')
+	})
+
+	it('scrubs a bearer header the vendor echoed back', () => {
+		const scrubbed = redactSecrets('bad header: Authorization: Bearer abcdef0123456789ABCDEF')
+		expect(scrubbed).not.toContain('abcdef0123456789ABCDEF')
+	})
+
+	it('scrubs a credential-named JSON field without eating the rest', () => {
+		const scrubbed = redactSecrets('{"api_key":"sk-live-9999","model":"the-model-that-failed"}')
+		expect(scrubbed).not.toContain('sk-live-9999')
+		// The surrounding sentence is the whole point — scrubbing must not
+		// degrade into deleting the message.
+		expect(scrubbed).toContain('the-model-that-failed')
+	})
+
+	it('scrubs on the real path, not only in the helper', () => {
+		const err = providerHttpError({
+			providerId: 'anthropic',
+			status: 401,
+			body: JSON.stringify({
+				error: { message: 'invalid key sk-ant-api03-AbCdEfGhIjKlMnOpQrStUv supplied' },
+			}),
+		})
+
+		expect(err.detail).not.toContain('AbCdEfGhIjKlMnOpQrStUv')
+		expect(err.detail).toContain('[redacted]')
+		expect(err.message).not.toContain('AbCdEfGhIjKlMnOpQrStUv')
+	})
+})

package/src/provider/errors.ts

@@ -11,11 +11,19 @@
  *
  * So the contract here is deliberately narrow:
  *
- *  - the message is built from the STATUS LINE and the classified `kind`. The
- *    response body is read to classify and then dropped. It is never
- *    interpolated, never re-thrown, and never attached as `cause` — a `cause`
- *    survives every logger that serializes an error chain, which defeats the
- *    point.
+ *  - the message is built from the STATUS LINE, the classified `kind`, and the
+ *    provider's own complaint in `detail` — truncated and scrubbed of anything
+ *    credential-shaped. The raw body is never re-thrown and never attached as
+ *    `cause`; a `cause` survives every logger that serializes an error chain,
+ *    which defeats the point.
+ *
+ *    The body used to be dropped entirely. That was over-corrected: a provider
+ *    rejecting a request names the exact offending field, and deleting that
+ *    sentence turned a one-line diagnosis into hypothesis elimination against a
+ *    live API — once at the cost of a day of production downtime, while the
+ *    wire had been saying `tools.0.custom.input_schema: … must match JSON
+ *    Schema draft 2020-12` the entire time. Scrubbing what looks like a
+ *    credential keeps the safety and returns the sentence.
  *  - `retryAfterMs` is DATA. Nothing in this module sleeps, backs off or
  *    retries. A retry loop inside a driver burns the run's wall clock and hides
  *    the failure from the layer that should decide.
@@ -50,6 +58,22 @@ export class ProviderRequestError extends Error {
 	public readonly providerId: string
 	public readonly status?: number
 	public readonly retryAfterMs?: number
+	/**
+	 * What the provider said was wrong, truncated and redacted.
+	 *
+	 * `ProviderRequestErrorInit` has declared this field all along and the
+	 * constructor never read it, so every caller that set it was writing to
+	 * nothing. That is not a cosmetic gap: a provider rejecting a request
+	 * usually names the exact offending field, and losing that sentence turns
+	 * a one-line diagnosis into hypothesis elimination against a live API. It
+	 * did — a tool schema in the wrong JSON Schema dialect cost a day of
+	 * production downtime while the wire had been saying
+	 * `tools.0.custom.input_schema: … must match JSON Schema draft 2020-12`
+	 * the whole time.
+	 *
+	 * See {@link vendorDetail} for what is kept and what is scrubbed.
+	 */
+	public readonly detail?: string
 
 	constructor(init: ProviderRequestErrorInit) {
 		super(buildProviderErrorMessage(init))
@@ -58,7 +82,80 @@ export class ProviderRequestError extends Error {
 		this.providerId = init.providerId
 		if (init.status !== undefined) this.status = init.status
 		if (init.retryAfterMs !== undefined) this.retryAfterMs = init.retryAfterMs
+		if (init.detail !== undefined) this.detail = init.detail
+	}
+}
+
+/** Longest detail worth carrying. A provider's complaint is a sentence. */
+const DETAIL_MAX = 400
+
+/**
+ * Credential shapes to scrub before a provider's words are kept.
+ *
+ * The original decision to discard the body outright was not paranoia — an
+ * error body can echo the request, and a request can carry a key. The answer
+ * is to scrub what looks like a credential rather than to throw away the
+ * sentence that names the broken field.
+ */
+const SECRET_PATTERNS: readonly RegExp[] = [
+	/\b(?:sk|pk|rk)[-_][A-Za-z0-9_-]{12,}/g,
+	/\bnpm_[A-Za-z0-9]{20,}/g,
+	/\bgh[pousr]_[A-Za-z0-9]{20,}/g,
+	/\bBearer\s+[A-Za-z0-9._~+/-]{12,}=*/gi,
+	/\bAKIA[0-9A-Z]{16}\b/g,
+	/("(?:api[_-]?key|authorization|token|secret|password)"\s*:\s*)"[^"]*"/gi,
+]
+
+/**
+ * The provider's own account of what was wrong, safe to log.
+ *
+ * Prefers the structured `error.message` a JSON body carries, because that is
+ * the field vendors put the actionable sentence in and it is bounded; falls
+ * back to the raw text. Truncated, and every credential shape replaced.
+ */
+export function vendorDetail(body: unknown): string | undefined {
+	if (body === undefined || body === null) return undefined
+
+	let text: string
+	if (typeof body === 'string') {
+		try {
+			text = pickMessage(JSON.parse(body)) ?? body
+		} catch {
+			text = body
+		}
+	} else {
+		text = pickMessage(body) ?? ''
+	}
+
+	const cleaned = redactSecrets(text.trim())
+	if (cleaned.length === 0) return undefined
+	return cleaned.length > DETAIL_MAX ? `${cleaned.slice(0, DETAIL_MAX)}…` : cleaned
+}
+
+export function redactSecrets(text: string): string {
+	let out = text
+	for (const pattern of SECRET_PATTERNS) {
+		out = out.replace(pattern, (_match, prefix?: string) =>
+			prefix === undefined ? '[redacted]' : `${prefix}"[redacted]"`,
+		)
+	}
+	return out
+}
+
+function pickMessage(value: unknown): string | undefined {
+	if (typeof value === 'string') return value
+	if (typeof value !== 'object' || value === null) return undefined
+	const node = value as Record<string, unknown>
+	// `{ error: { message } }` is what every wire in this tree uses; the rest
+	// are the shapes seen in the drivers' own fixtures.
+	const nested = node.error
+	if (typeof nested === 'string') return nested
+	if (typeof nested === 'object' && nested !== null) {
+		const message = (nested as Record<string, unknown>).message
+		if (typeof message === 'string') return message
 	}
+	if (typeof node.message === 'string') return node.message
+	return undefined
 }
 
 /** Is this a classified provider failure, whichever SDK copy threw it? */
@@ -312,11 +409,13 @@ export function providerVendorError(input: {
 		input.retryAfter ?? vendorRetryAfter(error),
 		input.now ?? Date.now(),
 	)
+	const detail = vendorDetail(message)
 	return new ProviderRequestError({
 		kind,
 		providerId: input.providerId,
 		...(status !== undefined ? { status } : {}),
 		...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+		...(detail !== undefined ? { detail } : {}),
 	})
 }
 
@@ -335,10 +434,12 @@ export function providerHttpError(input: {
 }): ProviderRequestError {
 	const kind = classifyProviderHttpStatus(input.status, input.body)
 	const retryAfterMs = parseRetryAfterMs(input.retryAfter, input.now ?? Date.now())
+	const detail = vendorDetail(input.body)
 	return new ProviderRequestError({
 		kind,
 		providerId: input.providerId,
 		status: input.status,
 		...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+		...(detail !== undefined ? { detail } : {}),
 	})
 }

package/src/provider/strict-schema.ts

@@ -28,12 +28,21 @@
  * A deny-list rather than an allow-list, deliberately. An allow-list would have
  * to enumerate every annotation a schema may carry — `description`, `title`,
  * `examples`, vendor extensions — and would refuse a schema for saying
- * something harmless. These are the constructs documented as outside the
- * subset; each one names what to write instead.
+ * something harmless. Each entry names what to write instead.
+ *
+ * MEASURED against the live API, not read off a page. The first version of this
+ * list was derived from documentation and was wrong in both directions: it
+ * refused `minLength`/`maxLength`, which the wire accepts, and it permitted
+ * `prefixItems`, which the wire rejects. A deny-list nobody probed is a guess
+ * with a confident tone, and this one would have refused working tools while
+ * still letting a broken one through.
+ *
+ * The probe lives in the live contract test; run it against a new model before
+ * trusting this list on that model.
  */
 const NO_CONDITIONALS = 'strict mode has no conditional schemas; flatten the object'
 const NO_NUMERIC_BOUNDS = 'numeric bounds are not in the subset; enforce at execution'
-const NO_LENGTH_BOUNDS = 'length bounds are not in the subset; enforce at execution'
+const NO_ARRAY_BOUNDS = 'array bounds are not in the subset; enforce at execution'
 
 // A Map rather than an object literal, because one of the keys is `then`: an
 // ordinary object carrying a `then` property is a thenable, and awaiting it
@@ -50,17 +59,40 @@ const UNSUPPORTED: ReadonlyMap<string, string> = new Map([
 	['exclusiveMinimum', NO_NUMERIC_BOUNDS],
 	['exclusiveMaximum', NO_NUMERIC_BOUNDS],
 	['multipleOf', NO_NUMERIC_BOUNDS],
-	['minLength', NO_LENGTH_BOUNDS],
-	['maxLength', NO_LENGTH_BOUNDS],
-	['minItems', NO_LENGTH_BOUNDS],
-	['maxItems', NO_LENGTH_BOUNDS],
-	['uniqueItems', 'array constraints are not in the subset; enforce at execution'],
+	// `minLength`/`maxLength` are NOT here. The first version of this list put
+	// them here on documentation alone, and measurement says the wire accepts
+	// both — so the list was refusing tools that would have worked. A deny-list
+	// derived from prose and never probed is a guess with a confident tone.
+	// `minItems` is NOT a flat denial — see MIN_ITEMS_ALLOWED below. The wire
+	// accepts 0 and 1 and refuses everything above, naming the value in the
+	// error, so a blanket entry here would refuse `.nonempty()` on a schema the
+	// wire would have taken.
+	['maxItems', NO_ARRAY_BOUNDS],
+	['uniqueItems', NO_ARRAY_BOUNDS],
+	// The other direction of the same mistake: this was missing, and it is the
+	// one that interacts with the dialect conversion. A tuple becomes
+	// `prefixItems` for the 2020-12 wire — and strict rejects `prefixItems`
+	// outright, so a tool that is BOTH strict AND tuple-shaped cannot be
+	// expressed at all. Better to say that at registration than to convert a
+	// schema into a different rejection.
+	['prefixItems', 'strict arrays take one `items` schema; a tuple cannot be expressed'],
 	['patternProperties', 'name the properties explicitly'],
 	['propertyNames', 'name the properties explicitly'],
 	['dependentSchemas', 'flatten the object and validate at execution'],
 	['dependentRequired', 'flatten the object and validate at execution'],
 ])
 
+/**
+ * The only `minItems` values the strict subset admits.
+ *
+ * Measured: `minItems: 0` and `minItems: 1` are accepted, `minItems: 2` comes
+ * back *"For 'array' type, 'minItems' values other than 0 or 1 are not
+ * supported"*. So the constraint is on the VALUE, not the keyword, and that is
+ * the whole difference between refusing a required-non-empty array — the
+ * ordinary spelling of `z.array(...).nonempty()` — and letting it through.
+ */
+const MIN_ITEMS_ALLOWED = new Set([0, 1])
+
 export interface StrictSchemaViolation {
 	/** Dotted path to the offending keyword, e.g. `properties.insertLine.oneOf`. */
 	readonly path: string
@@ -100,6 +132,31 @@ export function findStrictSchemaViolations(schema: unknown, path = ''): StrictSc
 			})
 			continue
 		}
+		// A tuple in the OTHER spelling. This check runs at registration, on the
+		// schema as rendered — which is draft-07, where a tuple is `items: [a,
+		// b]` — while the wire sees the 2020-12 `prefixItems` the driver
+		// converts it to. So a `prefixItems` entry alone never fires on the
+		// path that produces tuples, and the entry added to catch this case was
+		// dead for exactly the case it was added for.
+		//
+		// Both spellings mean the same thing and strict admits neither, so this
+		// names the tuple rather than the dialect it happens to be written in.
+		if (keyword === 'items' && Array.isArray(value)) {
+			found.push({
+				path: here,
+				keyword,
+				remedy: 'strict arrays take one `items` schema; a tuple cannot be expressed',
+			})
+			continue
+		}
+		if (keyword === 'minItems' && typeof value === 'number' && !MIN_ITEMS_ALLOWED.has(value)) {
+			found.push({
+				path: here,
+				keyword,
+				remedy: 'strict accepts `minItems` of 0 or 1 only; enforce a larger bound at execution',
+			})
+			continue
+		}
 		found.push(...findStrictSchemaViolations(value, here))
 	}
 	return found

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'
@@ -225,6 +232,10 @@ export {
 export { InMemoryThreadStore } from './store/thread/memory.js'
 
 export { LocalTaskGateway } from './gateway/local.js'
+// Exported because `buildCoordinatorTools` is: a host that builds the
+// coordinator surface itself needs the same inbox the loop drains, or its
+// abandoned completions go unheard exactly as they did before.
+export { CompletionInbox, formatCompletionNotification } from './gateway/completion-inbox.js'
 
 // ─── providers, sandbox, vault ───────────────────────────────────────────
 

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

@@ -0,0 +1,200 @@
+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('keeps a closed tuple closed', () => {
+		// This assertion used to be its own opposite, and the comment under it
+		// was wrong about the dialect: it claimed a closed tuple is 2020-12's
+		// default once `prefixItems` is set. It is not — with no `items`,
+		// elements past the tuple are UNCONSTRAINED. Dropping the `false`
+		// turned a schema written to forbid a third element into one that
+		// allows any, which is a silent widening rather than a saved byte.
+		expect(
+			toSchemaDialect(
+				{ type: 'array', items: [{ type: 'integer' }], additionalItems: false },
+				'2020-12',
+			),
+		).toEqual({ type: 'array', prefixItems: [{ type: 'integer' }], items: false })
+	})
+
+	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([])
+	})
+})