@namzu/sdk 5.1.0 → 6.0.0

package/src/provider/__tests__/strict-schema.test.ts

@@ -0,0 +1,189 @@
+import { describe, expect, it } from 'vitest'
+
+import { getBuiltinTools } from '../../tools/builtins/index.js'
+import { assertStrictSchema, findStrictSchemaViolations } from '../strict-schema.js'
+
+/**
+ * Strict tool input validates against a SUBSET of JSON Schema, and a keyword
+ * outside that subset is not degraded — the vendor rejects the entire request,
+ * so one unexpressible field in one tool takes down every tool in the call and
+ * the turn dies before producing a token.
+ *
+ * That shipped. The edit tool declared its integer-or-`"end"` field with
+ * `oneOf`, which is outside the subset while the equivalent `anyOf` is inside
+ * it, and the driver marked the tool strict without asking whether the schema
+ * it was vouching for could be said in that dialect.
+ *
+ * Measured against the live API:
+ *
+ * | body                   | result   |
+ * |------------------------|----------|
+ * | strict: true  + oneOf  | 400      |
+ * | strict: false + oneOf  | accepted |
+ * | strict: true  + anyOf  | accepted |
+ *
+ * The middle row is why nothing caught it. Neither half is wrong alone — the
+ * schema is valid JSON Schema, and turning strict on is correct policy — so no
+ * test of either one fails. Only the pairing does, and the pairing had no
+ * owner. The sweep below is that owner.
+ */
+
+describe('every tool that asks for strict validation can be expressed strictly', () => {
+	// The regression test that matters. Checking only the tool that broke
+	// would leave the next one to be found in production, which is how this
+	// one was found.
+	it.each(
+		getBuiltinTools()
+			.filter((t) => t.enforceModelInput)
+			.map((t) => [t.name, t] as const),
+	)('%s', (name, tool) => {
+		const violations = findStrictSchemaViolations(tool.modelInputSchema)
+		expect(violations, violations.map((v) => `${name}.${v.path}: ${v.remedy}`).join('\n')).toEqual(
+			[],
+		)
+	})
+
+	it('found at least one tool to check', () => {
+		// Guards the sweep itself: a filter that matches nothing passes
+		// vacuously, and a rename of `enforceModelInput` would silently turn
+		// this whole file into a no-op.
+		expect(getBuiltinTools().filter((t) => t.enforceModelInput).length).toBeGreaterThan(0)
+	})
+})
+
+describe('the violation report names the exact path', () => {
+	it('points at the keyword inside a nested property', () => {
+		const schema = {
+			type: 'object',
+			properties: {
+				insertLine: { oneOf: [{ type: 'integer' }, { const: 'end' }] },
+			},
+		}
+
+		expect(findStrictSchemaViolations(schema)).toEqual([
+			{
+				path: 'properties.insertLine.oneOf',
+				keyword: 'oneOf',
+				remedy: 'use `anyOf` — for disjoint branches the two are equivalent',
+			},
+		])
+	})
+
+	it('accepts the anyOf spelling of the same union', () => {
+		const schema = {
+			type: 'object',
+			properties: {
+				insertLine: { anyOf: [{ type: 'integer' }, { const: 'end' }] },
+			},
+		}
+
+		expect(findStrictSchemaViolations(schema)).toEqual([])
+	})
+
+	it('reports the bounds the wire refuses, and only those', () => {
+		// Measured against the live API rather than read off a page. The first
+		// version of this list was derived from documentation and was wrong in
+		// both directions: it refused `maxLength`, which the wire accepts, and
+		// permitted `prefixItems`, which it rejects.
+		const schema = {
+			type: 'object',
+			properties: {
+				n: { type: 'integer', minimum: 0 },
+				s: { type: 'string', maxLength: 10 },
+				a: { type: 'array', items: { type: 'string' }, maxItems: 3, minItems: 1 },
+			},
+		}
+
+		expect(
+			findStrictSchemaViolations(schema)
+				.map((v) => v.keyword)
+				.sort(),
+		).toEqual(['maxItems', 'minimum'])
+	})
+
+	it('leaves string length alone, because strict accepts it', () => {
+		// The false positive that would have refused tools which work.
+		expect(
+			findStrictSchemaViolations({ s: { type: 'string', minLength: 1, maxLength: 9 } }),
+		).toEqual([])
+	})
+
+	it('catches a tuple in either spelling, because strict admits neither', () => {
+		// The interaction worth pinning, and the one a `prefixItems` entry alone
+		// got wrong. This check runs at REGISTRATION, on the schema as rendered
+		// — draft-07, where a tuple is `items: [a, b]` — while the wire sees the
+		// `prefixItems` the driver converts it to. So denying only `prefixItems`
+		// was a guard that could not fire on the path that produces tuples.
+		//
+		// Measured, strict rejects both, which is why a tool that is both strict
+		// and tuple-shaped cannot be expressed at all. Converting it only
+		// changes which error comes back.
+		for (const items of [
+			{ prefixItems: [{ type: 'integer' }, { type: 'integer' }] },
+			{ items: [{ type: 'integer' }, { type: 'integer' }] },
+		]) {
+			const violations = findStrictSchemaViolations({
+				properties: { range: { type: 'array', ...items } },
+			})
+
+			expect(violations, JSON.stringify(items)).toHaveLength(1)
+			expect(violations[0]?.remedy).toContain('tuple cannot be expressed')
+		}
+	})
+
+	it('leaves an ordinary array alone, where `items` is one schema', () => {
+		// The false positive the tuple rule must not become: `items` is the
+		// normal spelling for a homogeneous array and strict accepts it. Only
+		// the array-of-schemas form is a tuple.
+		expect(findStrictSchemaViolations({ type: 'array', items: { type: 'string' } })).toEqual([])
+	})
+
+	it('admits minItems at 0 or 1 and refuses it above, as the wire does', () => {
+		// A blanket denial here was a false positive with a real cost: it
+		// refuses `z.array(...).nonempty()`, which renders `minItems: 1` and
+		// which the wire accepts. The constraint is on the VALUE, and the
+		// vendor's error says so — "'minItems' values other than 0 or 1 are not
+		// supported".
+		expect(findStrictSchemaViolations({ type: 'array', minItems: 0 })).toEqual([])
+		expect(findStrictSchemaViolations({ type: 'array', minItems: 1 })).toEqual([])
+
+		const violations = findStrictSchemaViolations({ type: 'array', minItems: 2 })
+		expect(violations).toHaveLength(1)
+		expect(violations[0]?.keyword).toBe('minItems')
+	})
+
+	it('admits additionalProperties only as false', () => {
+		expect(findStrictSchemaViolations({ additionalProperties: false })).toEqual([])
+		expect(findStrictSchemaViolations({ additionalProperties: { type: 'string' } })).toHaveLength(1)
+	})
+
+	it('walks into arrays of subschemas', () => {
+		const schema = { anyOf: [{ type: 'string' }, { not: { type: 'null' } }] }
+
+		expect(findStrictSchemaViolations(schema)[0]?.path).toBe('anyOf[1].not')
+	})
+
+	it('leaves ordinary annotations alone', () => {
+		const schema = {
+			type: 'object',
+			description: 'a tool',
+			properties: { a: { type: 'string', description: 'x', enum: ['y'] } },
+			required: ['a'],
+			additionalProperties: false,
+		}
+
+		expect(findStrictSchemaViolations(schema)).toEqual([])
+	})
+})
+
+describe('assertStrictSchema refuses rather than letting the request go', () => {
+	it('throws naming the tool, the path and the fix', () => {
+		expect(() => assertStrictSchema('edit', { properties: { insertLine: { oneOf: [] } } })).toThrow(
+			/edit\.properties\.insertLine\.oneOf/,
+		)
+	})
+
+	it('says nothing about a schema that is expressible', () => {
+		expect(() => assertStrictSchema('edit', { type: 'object' })).not.toThrow()
+	})
+})

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/model-version.ts

@@ -0,0 +1,98 @@
+/**
+ * Parse a versioned model id, given the vocabulary that names one.
+ *
+ * Several vendors spell an id the same way — a product segment, a family, a
+ * major version, sometimes a minor, and sometimes an 8-digit release date:
+ *
+ * ```
+ * <product>-<family>-<major>[-<minor>][-<YYYYMMDD>]
+ * ```
+ *
+ * The SHAPE is general and lives here; the vocabulary is not, and is supplied
+ * by the driver that knows it. That split is deliberate: a driver package
+ * exists to speak one service's dialect, and the kernel has no business
+ * knowing whose ids these are.
+ *
+ * It exists at all because three drivers had each written the same matcher and
+ * all three had the same defect: the minor-version group was `\d+`, which
+ * happily swallowed the date. An id naming no minor therefore parsed as
+ * `major.<the date>` and compared as enormously NEWER than one that does, so
+ * every capability gate keyed on `minor >= n` inverted for exactly those ids —
+ * a model was told it supported features it does not.
+ *
+ * A real minor version is one to three digits; a date is exactly eight.
+ * Bounding the group is what stops it reaching across the separator, and the
+ * expression then backtracks into leaving the minor absent so the date suffix
+ * can match where it belongs.
+ */
+
+export interface ModelVersion {
+	readonly family: string
+	readonly major: number
+	/** `0` when the id names no minor — a bare major is `<major>.0`. */
+	readonly minor: number
+}
+
+/**
+ * What a driver must say to have its ids parsed.
+ *
+ * Every field is a wire value the driver already carries. Passing them in
+ * rather than hard-coding them is what keeps this module free of any one
+ * service's names.
+ */
+export interface ModelIdGrammar {
+	/** The product segment an id begins with. */
+	readonly product: string
+	/** The family segment that follows it. */
+	readonly families: readonly string[]
+	/** An optional routing segment a gateway may prepend, including its slash. */
+	readonly routingPrefix?: string
+}
+
+const quoteMeta = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+function expressionFor(grammar: ModelIdGrammar): RegExp {
+	const routing = grammar.routingPrefix ? `(?:${quoteMeta(grammar.routingPrefix)})?` : ''
+	// `.map(quoteMeta)` and not `.map(escape)`: the latter resolves to the
+	// global, deprecated `escape()`, which percent-encodes instead of escaping
+	// regex metacharacters — and would pass every test here, because no family
+	// name contains a character either function changes.
+	const families = grammar.families.map((f) => quoteMeta(f)).join('|')
+	// `\d{1,3}` on the minor, not `\d+`. That single bound is the whole fix.
+	return new RegExp(
+		`^${routing}${quoteMeta(grammar.product)}-(${families})-(\\d+)(?:[-_.](\\d{1,3}))?(?:-\\d{8})?$`,
+	)
+}
+
+/** `undefined` for anything the grammar does not describe — never a guess. */
+export function parseVersionedModelId(
+	id: string,
+	grammar: ModelIdGrammar,
+): ModelVersion | undefined {
+	const match = id.toLowerCase().match(expressionFor(grammar))
+	if (!match) return undefined
+	return {
+		family: match[1] as string,
+		major: Number(match[2]),
+		minor: match[3] === undefined ? 0 : Number(match[3]),
+	}
+}
+
+/**
+ * Whether an id names a version at or above `major.minor`.
+ *
+ * The comparison every caller was writing by hand. An id this cannot parse
+ * returns `false`: a capability gate must not open for a name it does not
+ * understand, which is the fail-safe reading and the one those callers' own
+ * comments already claimed.
+ */
+export function modelVersionAtLeast(
+	id: string,
+	grammar: ModelIdGrammar,
+	major: number,
+	minor: number,
+): boolean {
+	const version = parseVersionedModelId(id, grammar)
+	if (!version) return false
+	return version.major > major || (version.major === major && version.minor >= minor)
+}