@namzu/sdk 5.0.0 → 5.2.0

package/src/registry/tool/__tests__/strict-registration.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+
+import type { ToolDefinition } from '../../../types/tool/index.js'
+import { ToolRegistry } from '../execute.js'
+
+/**
+ * A tool that asks for constrained generation and hands over a schema the
+ * constrained dialect cannot express is wrong at the moment it is DECLARED,
+ * whichever model it later meets.
+ *
+ * The first attempt at this check lived in a provider driver. That caught the
+ * bug — but per request, in one of the two drivers that mark tools strict, and
+ * only once something actually ran. The registry already refused
+ * `enforceModelInput` without a `modelInputSchema`, with a comment stating the
+ * principle exactly: "Refusing at registration puts the error where the author
+ * can fix it rather than at the first request." The rule was written down; the
+ * check was in the wrong place.
+ *
+ * So the pair is here now. One asks whether a model schema EXISTS, the other
+ * whether it can carry the guarantee the tool just requested.
+ */
+
+function tool(overrides: Partial<ToolDefinition>): ToolDefinition {
+	return {
+		name: 'sample',
+		description: 'a tool',
+		inputSchema: z.object({}),
+		execute: async () => ({ success: true, output: 'ok' }),
+		...overrides,
+	} as ToolDefinition
+}
+
+describe('a tool cannot register a schema its own guarantee cannot carry', () => {
+	it('refuses a keyword outside the strict subset, naming the path', () => {
+		const registry = new ToolRegistry()
+
+		expect(() =>
+			registry.register(
+				tool({
+					name: 'edit',
+					enforceModelInput: true,
+					modelInputSchema: {
+						type: 'object',
+						properties: { insertLine: { oneOf: [{ type: 'integer' }, { const: 'end' }] } },
+					},
+				}),
+			),
+		).toThrow(/edit\.properties\.insertLine\.oneOf/)
+	})
+
+	it('names the remedy, not just the offence', () => {
+		const registry = new ToolRegistry()
+
+		expect(() =>
+			registry.register(
+				tool({ enforceModelInput: true, modelInputSchema: { properties: { n: { minimum: 0 } } } }),
+			),
+		).toThrow(/enforce at execution/)
+	})
+
+	it('admits the same union spelled the way the subset accepts', () => {
+		const registry = new ToolRegistry()
+
+		expect(() =>
+			registry.register(
+				tool({
+					enforceModelInput: true,
+					modelInputSchema: {
+						type: 'object',
+						properties: { insertLine: { anyOf: [{ type: 'integer' }, { const: 'end' }] } },
+						additionalProperties: false,
+					},
+				}),
+			),
+		).not.toThrow()
+	})
+
+	it('leaves a tool that never asked for the guarantee alone', () => {
+		// Without `enforceModelInput` nothing is marked strict, so the schema is
+		// sent as ordinary JSON Schema and `oneOf` is perfectly legal there.
+		// Refusing it would break working setups for no reason.
+		const registry = new ToolRegistry()
+
+		expect(() =>
+			registry.register(
+				tool({ modelInputSchema: { properties: { a: { oneOf: [{ type: 'string' }] } } } }),
+			),
+		).not.toThrow()
+	})
+
+	it('still refuses enforcement with no model schema at all', () => {
+		// The check this one was added beside. Kept in the same file so a
+		// future edit sees both halves of the pair together.
+		const registry = new ToolRegistry()
+
+		expect(() => registry.register(tool({ enforceModelInput: true }))).toThrow(
+			/does not define modelInputSchema/,
+		)
+	})
+
+	it('refuses through every registration shape', () => {
+		// `register` has three overloads and only one of them was exercised
+		// above; a check on the wrong one would look like coverage.
+		const bad = tool({
+			name: 'bad',
+			enforceModelInput: true,
+			modelInputSchema: { properties: { a: { oneOf: [] } } },
+		})
+
+		expect(() => new ToolRegistry().register(bad)).toThrow(/oneOf/)
+		expect(() => new ToolRegistry().register('bad', bad)).toThrow(/oneOf/)
+		expect(() => new ToolRegistry().register([bad])).toThrow(/oneOf/)
+	})
+})

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/runtime/query/__tests__/stream-recovery.test.ts

@@ -182,6 +182,11 @@ describe('query stream recovery', () => {
 		const run = await drainQuery(
 			{
 				provider: new ClassifiedFailureProvider(),
+				// Retry off: this pins METADATA at the boundary, and a throttle
+				// is genuinely retryable — leaving retry on would spend the run's
+				// whole timeout backing off and settle it as a timeout instead,
+				// testing the retry policy rather than the thing named here.
+				retry: { maxRetries: 0 },
 				tools: new ToolRegistry(),
 				runConfig: {
 					model: 'mock-model',

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()
 

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/errors.ts

@@ -362,6 +362,62 @@ function codeFromStructure(err: unknown): ProviderErrorCode | undefined {
  *
  * Aborts are passed through untouched — see {@link isAbortError}.
  */
+/**
+ * Every `ProviderErrorKind`, mapped to what the runtime acts on.
+ *
+ * Read structurally rather than with `instanceof`: a driver in one package
+ * throws this and the runtime in another reads it, and two copies of the SDK
+ * in one process make `instanceof` unreliable — the same reason
+ * `isProviderRequestError` exists.
+ *
+ * `retryable` here is about whether resending the SAME request could succeed.
+ * `context_overflow` is correctly false — an identical prompt overflows
+ * identically — and it maps to `context_length_exceeded` so the loop can reach
+ * for compaction, which is a different remedy than a retry.
+ */
+const KIND_TO_CODE: Readonly<Record<string, { code: ProviderErrorCode; retryable: boolean }>> = {
+	throttle: { code: 'rate_limit', retryable: true },
+	network: { code: 'network', retryable: true },
+	server: { code: 'server_error', retryable: true },
+	auth: { code: 'auth', retryable: false },
+	context_overflow: { code: 'context_length_exceeded', retryable: false },
+	bad_request: { code: 'invalid_request', retryable: false },
+}
+
+function classifyFromProviderRequestError(
+	err: unknown,
+	providerId: string | undefined,
+	now: number,
+): ProviderError | undefined {
+	if (!(err instanceof Error) || err.name !== 'ProviderRequestError') return undefined
+	const candidate = err as Error & {
+		kind?: unknown
+		providerId?: unknown
+		status?: unknown
+		retryAfterMs?: unknown
+	}
+	if (typeof candidate.kind !== 'string') return undefined
+	const mapped = KIND_TO_CODE[candidate.kind]
+	if (!mapped) return undefined
+
+	const retryAfterMs =
+		typeof candidate.retryAfterMs === 'number' ? candidate.retryAfterMs : readRetryAfterMs(err, now)
+
+	return new ProviderError({
+		code: mapped.code,
+		message: err.message,
+		retryable: mapped.retryable,
+		cause: err,
+		...(typeof candidate.providerId === 'string'
+			? { providerId: candidate.providerId }
+			: providerId !== undefined
+				? { providerId }
+				: {}),
+		...(typeof candidate.status === 'number' ? { status: candidate.status } : {}),
+		...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+	})
+}
+
 export function classifyProviderError(
 	err: unknown,
 	providerId?: string,
@@ -369,6 +425,21 @@ export function classifyProviderError(
 ): ProviderError {
 	if (isProviderError(err)) return err
 
+	// A driver that already classified its own failure is read FIRST, and by
+	// its `kind` — the field it set on purpose.
+	//
+	// Without this the classifier fell through to the status heuristics, where
+	// a `ProviderRequestError` carrying `kind: 'context_overflow'` and a 400
+	// became `invalid_request`, non-retryable. Three of the six kinds landed
+	// wrong that way, and the consequences were not cosmetic: the loop's
+	// overflow branch tests for `context_length_exceeded`, so compaction relief
+	// — the one provider failure this kernel can actually do something about —
+	// was unreachable for exactly the drivers that had diagnosed it correctly.
+	// A driver that classified its own error came out worse than one that did
+	// not, which is the opposite of the incentive the type was created for.
+	const fromKind = classifyFromProviderRequestError(err, providerId, now)
+	if (fromKind) return fromKind
+
 	const message = err instanceof Error ? err.message : String(err)
 	const status = readStatus(err)
 	const errno = readErrnoCode(err)

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.
 	 *