@namzu/sdk 5.1.0 → 6.0.0

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/tool/execute.ts

@@ -1,4 +1,5 @@
 import { SpanStatusCode, context as otelContext, trace } from '@opentelemetry/api'
+import { assertStrictSchema } from '../../provider/strict-schema.js'
 import { GENAI, NAMZU, toolSpanName } from '../../telemetry/attributes.js'
 import { recordToolCall } from '../../telemetry/metrics.js'
 import { getTracer } from '../../telemetry/runtime-accessors.js'
@@ -177,6 +178,21 @@ export class ToolRegistry extends ManagedRegistry<ToolDefinition> {
 				`Tool "${id}" enables enforceModelInput but does not define modelInputSchema. Constrained input generation requires an explicit provider-safe model schema.`,
 			)
 		}
+		// …and the schema has to be one a constrained decoder can actually be
+		// given. The check above asks whether a model schema EXISTS; this asks
+		// whether it can carry the guarantee the tool just requested.
+		//
+		// Both belong here for the reason the comment above already states.
+		// Strict validation runs against a SUBSET of JSON Schema, and a keyword
+		// outside it is not degraded — the request is rejected whole, so one
+		// unexpressible field takes down every other tool in the call. The
+		// first version of this check lived in a provider driver, which meant
+		// it fired per request, in one driver, long after the author had moved
+		// on. A tool that asks for a guarantee its own schema cannot carry is
+		// wrong at the moment it is declared, whichever model it later meets.
+		if (tool.enforceModelInput) {
+			assertStrictSchema(id, tool.modelInputSchema)
+		}
 		if (tool.tier && this.tierConfig) {
 			const validIds = this.tierConfig.tiers.map((t) => t.id)
 			if (!validIds.includes(tool.tier)) {

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

@@ -47,6 +47,11 @@ export class ResultAssembler {
 			type: 'run_completed',
 			runId: runMgr.id,
 			result: runMgr.getRun().result ?? '',
+			// Read AFTER `markCompleted`, which is where a run that was stopped
+			// mid-flight has its reason settled. Carried on the event so a
+			// consumer can tell "answered" from "ran out of budget" without
+			// holding the `Run`.
+			...(runMgr.getRun().stopReason ? { stopReason: runMgr.getRun().stopReason } : {}),
 		})
 		yield* drainPending()
 
@@ -124,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/tools/builtins/__tests__/edit-insert-reachable.test.ts

@@ -70,12 +70,18 @@ describe('the model can emit the idiom the description recommends', () => {
 	})
 
 	it('admits only "end" as a string, so a synonym cannot be generated', () => {
-		const insert = (schema().properties as Record<string, { oneOf?: unknown[] }>).insertLine
+		const insert = (schema().properties as Record<string, { anyOf?: unknown[] }>).insertLine
 
 		// The schema is where the synonym problem is solved for a provider that
 		// constrains: `"EOF"` is not emittable because `"end"` is the only
 		// string the union admits.
-		expect(insert?.oneOf).toEqual([{ type: 'integer', minimum: 0 }, { const: 'end' }])
+		//
+		// `anyOf`, not `oneOf`: strict tool use validates against a subset of
+		// JSON Schema that excludes `oneOf`, and the vendor rejects the whole
+		// request rather than one field — so the spelling here is load-bearing,
+		// not stylistic. The two are equivalent for disjoint branches.
+		// `minimum` is gone for the same reason; the execution schema keeps it.
+		expect(insert?.anyOf).toEqual([{ type: 'integer' }, { const: 'end' }])
 	})
 })
 

package/src/tools/builtins/__tests__/edit.test.ts

@@ -39,7 +39,7 @@ describe('EditTool', () => {
 						'Exact replacement text. May be empty to delete old_string. Keep under 12000 characters.',
 				},
 				insertLine: {
-					oneOf: [{ type: 'integer', minimum: 0 }, { const: 'end' }],
+					anyOf: [{ type: 'integer' }, { const: 'end' }],
 					description:
 						'Insert instead of replacing. The new_string goes after this 1-indexed line; 0 inserts before the first line; "end" appends. Omit for a find-and-replace.',
 				},

package/src/tools/builtins/edit.ts

@@ -102,12 +102,30 @@ const modelInputSchema: Record<string, unknown> = {
 		},
 		insertLine: {
 			// The union the execution schema already accepts, stated so a
-			// constrained decoder can emit it. Declaring it as `oneOf` of an
+			// constrained decoder can emit it. Stating it as a union of an
 			// integer and the literal `"end"` also makes the synonym problem
 			// structurally impossible: `"EOF"`, `"append"` and `"last"` are
 			// not emittable, because `"end"` is the only string the schema
 			// admits.
-			oneOf: [{ type: 'integer', minimum: 0 }, { const: 'end' }],
+			//
+			// `anyOf`, NOT `oneOf`. Strict tool use validates against a SUBSET
+			// of JSON Schema, and `oneOf` is not in it — the vendor rejects the
+			// whole request with `tools.N.custom: Schema type 'oneOf' is not
+			// supported`, so the tool never mounts and the turn dies before a
+			// single token. Measured against the live API: strict + `oneOf` is
+			// a 400, strict + `anyOf` is accepted, and non-strict + `oneOf` is
+			// accepted — which is why nothing caught it. Both halves were
+			// individually fine; only their combination fails, and strict is on
+			// for every model at or above the gate.
+			//
+			// The two branches are disjoint, so `anyOf` and `oneOf` mean the
+			// same thing here — nothing is loosened.
+			//
+			// `minimum` is gone for the same reason: numeric constraints are
+			// outside the strict subset too. The bound is not lost — the
+			// execution schema still enforces it, which is where a value that
+			// crosses a boundary should be checked anyway.
+			anyOf: [{ type: 'integer' }, { const: 'end' }],
 			description:
 				'Insert instead of replacing. The new_string goes after this 1-indexed line; 0 inserts before the first line; "end" appends. Omit for a find-and-replace.',
 		},

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
 }

package/src/types/run/events.ts

@@ -16,7 +16,7 @@ import type { PlanStep } from '../plan/index.js'
 import type { PluginHookEvent, PluginHookResult } from '../plugin/index.js'
 import type { TaskStatus } from '../task/index.js'
 import type { Lineage } from './lineage.js'
-import type { MessageStopReason } from './stop-reason.js'
+import type { MessageStopReason, StopReason } from './stop-reason.js'
 import type {
 	SubsessionIdledEvent,
 	SubsessionMessagedEvent,
@@ -252,7 +252,20 @@ type CoreRunEvent =
 			guardrail?: string
 			reason?: string
 	  }
-	| { type: 'run_completed'; runId: RunId; result: string }
+	/**
+	 * The run reached its end without throwing.
+	 *
+	 * `completed` is not `succeeded`. A run stopped by its token budget, its
+	 * timeout, its iteration cap, a cancellation or a blocking output guardrail
+	 * all arrive here — `run_failed` is emitted only from the throw path — so a
+	 * consumer that treated this event as success reported one for a run whose
+	 * answer was refused. Measured: `max_iterations` produces
+	 * `status: 'completed'` with `result` holding whatever partial text existed.
+	 *
+	 * `stopReason` is what separates them, and it is on the event because the
+	 * alternative is asking every consumer to hold the `Run` as well.
+	 */
+	| { type: 'run_completed'; runId: RunId; result: string; stopReason?: StopReason }
 	/**
 	 * The run failed.
 	 *