@namzu/sdk 1.3.0 → 2.0.0

package/src/provider/errors.ts

@@ -0,0 +1,344 @@
+/**
+ * One classified error for every provider failure.
+ *
+ * Before this, a failure from any of the seven drivers reached the caller as an
+ * opaque string, so nothing downstream could decide whether it was worth
+ * retrying, whether it was the caller's fault, or whether the context window had
+ * simply run out. Two drivers built that string by interpolating the response
+ * body; three more inherited a vendor SDK error whose message IS the response
+ * body. Either way, a credential the upstream echoed back landed in a message
+ * that gets logged.
+ *
+ * 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.
+ *  - `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.
+ */
+
+import type { ProviderErrorKind, ProviderRequestErrorInit } from '../types/provider/error.js'
+export type {
+	ProviderErrorInfo,
+	ProviderErrorKind,
+	ProviderRequestErrorInit,
+} from '../types/provider/error.js'
+
+const PROVIDER_ERROR_KINDS: readonly ProviderErrorKind[] = [
+	'throttle',
+	'network',
+	'auth',
+	'context_overflow',
+	'bad_request',
+	'server',
+]
+
+/**
+ * A provider request that failed, classified.
+ *
+ * `name` is set explicitly rather than inherited, because the classifier is
+ * matched structurally across a package boundary (a driver in one package throws
+ * it; the runtime in another reads it) and `instanceof` is unreliable when two
+ * copies of the SDK end up in one process.
+ */
+export class ProviderRequestError extends Error {
+	public readonly kind: ProviderErrorKind
+	public readonly providerId: string
+	public readonly status?: number
+	public readonly retryAfterMs?: number
+
+	constructor(init: ProviderRequestErrorInit) {
+		super(buildProviderErrorMessage(init))
+		this.name = 'ProviderRequestError'
+		this.kind = init.kind
+		this.providerId = init.providerId
+		if (init.status !== undefined) this.status = init.status
+		if (init.retryAfterMs !== undefined) this.retryAfterMs = init.retryAfterMs
+	}
+}
+
+/** Is this a classified provider failure, whichever SDK copy threw it? */
+export function isProviderRequestError(err: unknown): err is ProviderRequestError {
+	return (
+		err instanceof Error &&
+		err.name === 'ProviderRequestError' &&
+		typeof (err as { providerId?: unknown }).providerId === 'string' &&
+		PROVIDER_ERROR_KINDS.includes((err as { kind?: ProviderErrorKind }).kind as ProviderErrorKind)
+	)
+}
+
+/**
+ * Did the caller's own AbortSignal terminate this request?
+ *
+ * Provider SDKs do not agree on the object they reject with: some preserve
+ * `signal.reason`, while others replace it with `AbortError` or
+ * `APIUserAbortError`. Reclassifying any of those as a network failure breaks
+ * the runtime's Stop/cancel path, which depends on the abort escaping the
+ * provider boundary.
+ *
+ * The signal must itself be aborted. That condition distinguishes a caller Stop
+ * from an SDK timeout which may also use an `AbortError`-shaped rejection.
+ */
+export function isCallerAbortError(error: unknown, signal?: AbortSignal): boolean {
+	if (!signal?.aborted) return false
+	if (error === signal.reason) return true
+	if (!(error instanceof Error)) return false
+	return error.name === 'AbortError' || error.name === 'APIUserAbortError'
+}
+
+const KIND_SENTENCE: Record<ProviderErrorKind, string> = {
+	throttle: 'rate limited by the provider',
+	network: 'could not reach the provider',
+	auth: 'the provider rejected the request credentials',
+	context_overflow: 'the request exceeded the model context window',
+	bad_request: 'the provider rejected the request as invalid',
+	server: 'the provider failed to complete the request',
+}
+
+function buildProviderErrorMessage(init: ProviderRequestErrorInit): string {
+	const status = init.status !== undefined ? ` (HTTP ${init.status})` : ''
+	const detail = init.detail ? `: ${init.detail}` : ''
+	return `${init.providerId}${status} — ${KIND_SENTENCE[init.kind]}${detail}`
+}
+
+/**
+ * Body fragments that mean "the request did not fit", across the vendors we
+ * drive. Matched case-insensitively against the raw body, which is then
+ * discarded.
+ *
+ * A 400 is otherwise `bad_request`: an overflow is the one 400 a caller can act
+ * on automatically (compact and retry), and mistaking a genuine schema error for
+ * an overflow would send the run into a pointless compaction loop.
+ */
+const OVERFLOW_BODY_PATTERNS: readonly RegExp[] = [
+	/prompt is too long/i,
+	/context[_ ]length[_ ]exceeded/i,
+	/maximum context length/i,
+	/too long for requested model/i,
+	/input is too long/i,
+	/(?:input|prompt|context).{0,80}exceeds the maximum/i,
+	/reduce the (?:input|prompt|context) length/i,
+	// Ollama phrases it the other way round — "input length exceeds context
+	// length" — so a pattern anchored on "exceeded" misses it entirely.
+	/exceeds?\s+(?:the\s+)?(?:model'?s?\s+)?context\s+(?:length|window|size)/i,
+	/context\s+(?:length|window|size)\s+exceed/i,
+]
+
+/** Does this response body say the request did not fit the window? */
+export function bodySaysContextOverflow(body: string | undefined | null): boolean {
+	if (!body) return false
+	return OVERFLOW_BODY_PATTERNS.some((re) => re.test(body))
+}
+
+/**
+ * `Retry-After` in milliseconds. The header is either delta-seconds or an
+ * HTTP-date; both are specified, and vendors use both.
+ *
+ * Returns undefined for anything unparseable or for a date already in the past —
+ * a negative delay is worse than none, because a caller would treat it as
+ * "retry immediately" against a provider that just asked it to wait.
+ */
+export function parseRetryAfterMs(
+	headerValue: string | null | undefined,
+	now: number = Date.now(),
+): number | undefined {
+	if (!headerValue) return undefined
+	const trimmed = headerValue.trim()
+	if (trimmed === '') return undefined
+
+	if (/^\d+(\.\d+)?$/.test(trimmed)) {
+		const seconds = Number(trimmed)
+		if (!Number.isFinite(seconds) || seconds < 0) return undefined
+		return Math.round(seconds * 1000)
+	}
+
+	const at = Date.parse(trimmed)
+	if (Number.isNaN(at)) return undefined
+	const delta = at - now
+	return delta > 0 ? delta : undefined
+}
+
+/**
+ * Classify an HTTP failure. `body` is used ONLY to separate a context overflow
+ * from an ordinary bad request, and is not retained.
+ */
+export function classifyProviderHttpStatus(
+	status: number,
+	body?: string | null,
+): ProviderErrorKind {
+	if (status === 401 || status === 403) return 'auth'
+	if (status === 429) return 'throttle'
+	if (status === 408 || status === 425) return 'network'
+	if (status >= 500) return 'server'
+	if (status === 413) {
+		return bodySaysContextOverflow(body) ? 'context_overflow' : 'bad_request'
+	}
+	if (status >= 400) {
+		return bodySaysContextOverflow(body) ? 'context_overflow' : 'bad_request'
+	}
+	// A non-failure status reaching here is a caller bug, not a provider one.
+	return 'server'
+}
+
+/**
+ * Vendor error TYPES, as the vendors name them in their own payloads. This is a
+ * defined vocabulary, not prose, which is what makes it safe to classify on:
+ * Anthropic sends `{"error":{"type":"overloaded_error"}}` and OpenAI sends
+ * `{"error":{"code":"context_length_exceeded"}}`.
+ *
+ * It matters for MID-STREAM failures above all. Those arrive after a 200, so
+ * there is no status to classify from, and without this an upstream overload
+ * would be filed as `network` — "we could not reach the provider" — when the
+ * provider answered and then gave up. The distinction is the whole point of the
+ * taxonomy: one is worth retrying elsewhere, the other is worth retrying here.
+ */
+const VENDOR_TYPE_KINDS: ReadonlyArray<readonly [RegExp, ProviderErrorKind]> = [
+	[/overloaded_error|api_error|service_unavailable/i, 'server'],
+	[/rate_limit_error|rate_limit_exceeded/i, 'throttle'],
+	[/authentication_error|permission_error|invalid_api_key|unauthorized/i, 'auth'],
+	[/timeout_error|connection_error/i, 'network'],
+]
+
+/** The kind a vendor's own error-type vocabulary implies, if it says one. */
+function vendorTypeKind(message: string): ProviderErrorKind | undefined {
+	for (const [re, kind] of VENDOR_TYPE_KINDS) {
+		if (re.test(message)) return kind
+	}
+	return undefined
+}
+
+/**
+ * Status code off a vendor SDK's own error object, whatever it calls the field.
+ * Anthropic and OpenAI use `status`; the ollama client uses `status_code`; AWS
+ * puts it under `$metadata.httpStatusCode`.
+ */
+function vendorErrorStatus(err: unknown): number | undefined {
+	if (typeof err !== 'object' || err === null) return undefined
+	const e = err as {
+		status?: unknown
+		statusCode?: unknown
+		status_code?: unknown
+		$metadata?: { httpStatusCode?: unknown }
+	}
+	for (const candidate of [e.status, e.statusCode, e.status_code, e.$metadata?.httpStatusCode]) {
+		if (typeof candidate === 'number' && Number.isFinite(candidate)) return candidate
+	}
+	return undefined
+}
+
+/**
+ * `retry-after` off a vendor SDK error's captured response headers. The
+ * Anthropic and OpenAI clients both attach them (as a `Headers` instance or a
+ * plain object depending on version); the ollama client throws them away, which
+ * is why `retryAfterMs` is genuinely unavailable on that driver.
+ */
+function vendorRetryAfter(err: unknown): string | undefined {
+	if (typeof err !== 'object' || err === null) return undefined
+	// AWS keeps the response one level down, on `$response`; the Anthropic and
+	// OpenAI clients attach `headers` directly.
+	const headers =
+		(err as { headers?: unknown }).headers ??
+		(err as { $response?: { headers?: unknown } }).$response?.headers
+	if (!headers) return undefined
+	if (typeof (headers as Headers).get === 'function') {
+		return (headers as Headers).get('retry-after') ?? undefined
+	}
+	const record = headers as Record<string, unknown>
+	for (const key of ['retry-after', 'Retry-After', 'retryAfter']) {
+		const value = record[key]
+		if (typeof value === 'string') return value
+	}
+	return undefined
+}
+
+/**
+ * Classify an error thrown by a vendor SDK and replace it.
+ *
+ * This exists because wrapping our OWN `!response.ok` throws is not enough. The
+ * Anthropic, OpenAI and ollama clients each build their error message FROM the
+ * response body, so a credential the upstream echoed back is already inside
+ * `err.message` before our code sees it. Proven with a planted fake token on all
+ * three.
+ *
+ * So the vendor error is read for its status and scanned for an overflow
+ * signature, and then **dropped entirely** — not re-thrown, not wrapped, and not
+ * attached as `cause`. A `cause` is exactly what a structured logger walks, so
+ * keeping one for debuggability would reintroduce the leak it is meant to close.
+ *
+ * `name` is checked too, because AWS models its failures as distinct classes
+ * (`ThrottlingException`, `ValidationException`, `AccessDeniedException`) rather
+ * than as status codes.
+ */
+export function providerVendorError(input: {
+	readonly providerId: string
+	readonly error: unknown
+	readonly retryAfter?: string | null
+	readonly now?: number
+}): ProviderRequestError {
+	const { error } = input
+	const status = vendorErrorStatus(error)
+	const name = error instanceof Error ? error.name : ''
+	const message = error instanceof Error ? error.message : ''
+
+	let kind: ProviderErrorKind
+	if (/ThrottlingException|TooManyRequests|ServiceQuotaExceeded/i.test(name)) {
+		kind = 'throttle'
+	} else if (/AccessDenied|Unauthorized|Forbidden|Authentication/i.test(name)) {
+		kind = 'auth'
+	} else if (/ValidationException/i.test(name)) {
+		kind = bodySaysContextOverflow(message) ? 'context_overflow' : 'bad_request'
+	} else if (
+		/ServiceUnavailable|InternalServer|ModelTimeout|ModelStreamError|ModelError|ModelNotReady/i.test(
+			name,
+		)
+	) {
+		kind = 'server'
+	} else if (status !== undefined) {
+		kind = classifyProviderHttpStatus(status, message)
+	} else if (bodySaysContextOverflow(message)) {
+		kind = 'context_overflow'
+	} else {
+		// No status: a mid-stream failure, or a transport error. The vendor's own
+		// error-type vocabulary is the only signal left; absent that, the request
+		// genuinely did not get an answer.
+		kind = vendorTypeKind(message) ?? 'network'
+	}
+
+	const retryAfterMs = parseRetryAfterMs(
+		input.retryAfter ?? vendorRetryAfter(error),
+		input.now ?? Date.now(),
+	)
+	return new ProviderRequestError({
+		kind,
+		providerId: input.providerId,
+		...(status !== undefined ? { status } : {}),
+		...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+	})
+}
+
+/**
+ * Build a classified error from a failed HTTP response.
+ *
+ * Callers pass the body they already read for classification; this function
+ * does not return it, store it, or put it in the message.
+ */
+export function providerHttpError(input: {
+	readonly providerId: string
+	readonly status: number
+	readonly body?: string | null
+	readonly retryAfter?: string | null
+	readonly now?: number
+}): ProviderRequestError {
+	const kind = classifyProviderHttpStatus(input.status, input.body)
+	const retryAfterMs = parseRetryAfterMs(input.retryAfter, input.now ?? Date.now())
+	return new ProviderRequestError({
+		kind,
+		providerId: input.providerId,
+		status: input.status,
+		...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+	})
+}

package/src/provider/index.ts

@@ -1,3 +1,18 @@
+export {
+	ProviderRequestError,
+	isCallerAbortError,
+	isProviderRequestError,
+	classifyProviderHttpStatus,
+	bodySaysContextOverflow,
+	parseRetryAfterMs,
+	providerHttpError,
+	providerVendorError,
+} from './errors.js'
+export type {
+	ProviderErrorInfo,
+	ProviderErrorKind,
+	ProviderRequestErrorInit,
+} from './errors.js'
 export {
 	ProviderRegistry,
 	UnknownProviderError,

package/src/public-runtime.ts

@@ -47,11 +47,19 @@ export * from './utils/id.js'
 
 // ─── utility helpers ─────────────────────────────────────────────────────
 
-export { accumulateCost, calculateCost, formatCost, ZERO_COST } from './utils/cost.js'
+export {
+	accumulateCost,
+	calculateCost,
+	formatCost,
+	ZERO_COST,
+} from './utils/cost.js'
 export { toErrorMessage } from './utils/error.js'
 export { configureLogger, getRootLogger, Logger } from './utils/logger.js'
 export { buildToolResultHashes, hashToolResult } from './utils/hash.js'
-export { compressShellOutput, compressShellOutputFull } from './utils/shell-compress.js'
+export {
+	compressShellOutput,
+	compressShellOutputFull,
+} from './utils/shell-compress.js'
 export { createChildAbortController } from './utils/abort.js'
 export { memoizeAsync } from './utils/memoize.js'
 export { extractFinalResponse } from './utils/conversation.js'
@@ -61,7 +69,10 @@ export { extractFinalResponse } from './utils/conversation.js'
 export { resolveTaskModel } from './router/task-router.js'
 export { drainQuery, query } from './runtime/query/index.js'
 export { ContextCache } from './runtime/query/context-cache.js'
-export { CheckpointManager, projectEmergencyToCheckpoint } from './runtime/query/checkpoint.js'
+export {
+	CheckpointManager,
+	projectEmergencyToCheckpoint,
+} from './runtime/query/checkpoint.js'
 export { prepareReplayState } from './runtime/query/replay/prepare.js'
 export { listCheckpoints } from './runtime/query/replay/list.js'
 export { DecisionParser, FallbackResolver } from './runtime/decision/index.js'
@@ -73,8 +84,17 @@ export {
 
 // ─── personas, skills, advisory ──────────────────────────────────────────
 
-export { assembleSystemPrompt, mergePersonas, withSessionContext } from './persona/index.js'
-export { discoverSkills, loadSkill, resolveSkillChain, SkillRegistry } from './skills/index.js'
+export {
+	assembleSystemPrompt,
+	mergePersonas,
+	withSessionContext,
+} from './persona/index.js'
+export {
+	discoverSkills,
+	loadSkill,
+	resolveSkillChain,
+	SkillRegistry,
+} from './skills/index.js'
 export {
 	AdvisorRegistry,
 	AdvisoryContext,
@@ -144,19 +164,30 @@ export { LocalTaskGateway } from './gateway/local.js'
 // ─── providers, sandbox, vault ───────────────────────────────────────────
 
 export {
+	bodySaysContextOverflow,
+	classifyProviderHttpStatus,
 	DuplicateProviderError,
+	isCallerAbortError,
+	isProviderRequestError,
 	LazyProviderLoadError,
 	LazyProviderSyncCreateError,
 	MOCK_CAPABILITIES,
 	MockLLMProvider,
+	parseRetryAfterMs,
 	PERMISSIVE_PROVIDER_CAPABILITIES,
+	providerHttpError,
+	providerVendorError,
 	ProviderRegistry,
+	ProviderRequestError,
 	registerMock,
 	resolveProviderCapabilities,
 	UnknownProviderError,
 } from './provider/index.js'
 
-export { LocalSandboxProvider, SandboxProviderFactory } from './sandbox/index.js'
+export {
+	LocalSandboxProvider,
+	SandboxProviderFactory,
+} from './sandbox/index.js'
 
 export { InMemoryCredentialVault } from './vault/index.js'
 
@@ -222,7 +253,10 @@ export {
 	runToA2ATask,
 } from './bridge/a2a/index.js'
 
-export { mapRunToStreamEvent, mapSessionToStreamEvent } from './bridge/sse/index.js'
+export {
+	mapRunToStreamEvent,
+	mapSessionToStreamEvent,
+} from './bridge/sse/index.js'
 
 // ─── bus, verification ───────────────────────────────────────────────────
 
@@ -355,10 +389,19 @@ export {
 // ─── runtime helpers colocated with shapes under `types/` (§1.5) ─────────
 
 export { A2AProtocolError } from './types/a2a/index.js'
-export { isTerminalActivityStatus, resolveActivityTracking } from './types/activity/index.js'
+export {
+	isTerminalActivityStatus,
+	resolveActivityTracking,
+} from './types/activity/index.js'
 export { isTerminalAgentTaskState } from './types/agent/task.js'
-export { accumulateTokenUsage, isTerminalStatus } from './types/common/index.js'
-export { assertComputerUseActionType, assertDisplayServer } from './types/computer-use/index.js'
+export {
+	accumulateTokenUsage,
+	isTerminalStatus,
+} from './types/common/index.js'
+export {
+	assertComputerUseActionType,
+	assertDisplayServer,
+} from './types/computer-use/index.js'
 export { isConnectorActive } from './types/connector/core.js'
 export { CONNECTOR_SCOPE_ORDER } from './types/connector/scope.js'
 export { RoutingResponseSchema } from './types/decision/index.js'

package/src/registry/tool/execute.test.ts

@@ -98,6 +98,17 @@ describe('ToolRegistry — register + availability', () => {
 		expect(() => r.register('oops', 'not-a-tool' as never)).toThrow(/requires a ToolDefinition/)
 	})
 
+	it('rejects enforced model input without an explicit model schema', () => {
+		const r = new ToolRegistry()
+		expect(() =>
+			r.register(
+				makeTool('unsafe_strict', {
+					enforceModelInput: true,
+				}),
+			),
+		).toThrow(/enforceModelInput.*modelInputSchema/)
+	})
+
 	it('getAvailability returns active for unknown names (current default)', () => {
 		const r = new ToolRegistry()
 		expect(r.getAvailability('never-registered')).toBe('active')
@@ -228,7 +239,10 @@ describe('ToolRegistry — searchDeferred', () => {
 		r.register(
 			[
 				makeTool('send_invoice', {
-					inputSchema: z.object({ customerEmail: z.string(), amount: z.number() }),
+					inputSchema: z.object({
+						customerEmail: z.string(),
+						amount: z.number(),
+					}),
 				}),
 			],
 			'deferred',
@@ -237,10 +251,50 @@ describe('ToolRegistry — searchDeferred', () => {
 		expect(r.searchDeferred('customerEmail').map((t) => t.name)).toEqual(['send_invoice'])
 	})
 
+	it('indexes canonical model-schema branches without re-advertising runtime aliases', () => {
+		const r = new ToolRegistry()
+		r.register(
+			[
+				makeTool('edit_document', {
+					inputSchema: z.object({ oldStr: z.string(), newStr: z.string() }),
+					modelInputSchema: {
+						type: 'object',
+						properties: {
+							path: { type: 'string' },
+							old_string: { type: 'string' },
+							new_string: { type: 'string' },
+						},
+						required: ['path', 'new_string'],
+						additionalProperties: false,
+						anyOf: [
+							{
+								type: 'object',
+								properties: {
+									path: { type: 'string' },
+									old_string: { type: 'string' },
+									new_string: { type: 'string' },
+								},
+								required: ['path', 'old_string', 'new_string'],
+								additionalProperties: false,
+							},
+						],
+					},
+				}),
+			],
+			'deferred',
+		)
+		expect(r.searchDeferred('old_string').map((t) => t.name)).toEqual(['edit_document'])
+		expect(r.searchDeferred('oldStr')).toEqual([])
+	})
+
 	it('stops generic CRUD verbs so they cannot activate catalog slices', () => {
 		const r = new ToolRegistry()
 		r.register(
-			[makeTool('list_deals', { description: 'List the deals in an account.' })],
+			[
+				makeTool('list_deals', {
+					description: 'List the deals in an account.',
+				}),
+			],
 			'deferred',
 		)
 		r.register([makeTool('list_workflows', { description: 'List workflows.' })], 'deferred')
@@ -370,6 +424,34 @@ describe('ToolRegistry — toPromptSection + toLLMTools', () => {
 		expect(names).toEqual(['a', 'c'])
 	})
 
+	it('toLLMTools: prefers a canonical model schema over runtime compatibility aliases', () => {
+		const r = new ToolRegistry()
+		const modelInputSchema = {
+			type: 'object',
+			properties: { new_string: { type: 'string' } },
+			required: ['new_string'],
+			additionalProperties: false,
+		}
+		r.register(
+			makeTool('edit', {
+				inputSchema: z.object({
+					new_string: z.string().optional(),
+					newStr: z.string().optional(),
+				}),
+				modelInputSchema,
+			}),
+		)
+
+		const firstSchema = r.toLLMTools()[0]?.function.parameters
+		expect(firstSchema).toEqual(modelInputSchema)
+		expect(firstSchema).not.toBe(modelInputSchema)
+		;(firstSchema?.properties as Record<string, unknown>).newStr = { type: 'string' }
+
+		const nextSchema = r.toLLMTools()[0]?.function.parameters
+		expect(nextSchema).toEqual(modelInputSchema)
+		expect(JSON.stringify(nextSchema)).not.toContain('newStr')
+	})
+
 	it('toLLMTools: prefixes description with tier label when labelInDescription is true', () => {
 		const tierConfig: ToolTierConfig = {
 			tiers: [{ id: 'safe', label: 'Safe', priority: 1 }],
@@ -398,7 +480,11 @@ describe('ToolRegistry — execute', () => {
 			'write',
 			{},
 			makeContext({
-				permissionContext: { mode: 'plan', runId: 'run_1', workingDirectory: '/tmp' },
+				permissionContext: {
+					mode: 'plan',
+					runId: 'run_1',
+					workingDirectory: '/tmp',
+				},
 			}),
 		)
 		expect(result.success).toBe(false)
@@ -413,7 +499,11 @@ describe('ToolRegistry — execute', () => {
 			'read',
 			{},
 			makeContext({
-				permissionContext: { mode: 'plan', runId: 'run_1', workingDirectory: '/tmp' },
+				permissionContext: {
+					mode: 'plan',
+					runId: 'run_1',
+					workingDirectory: '/tmp',
+				},
 			}),
 		)
 		expect(result.success).toBe(true)
@@ -433,11 +523,28 @@ describe('ToolRegistry — execute', () => {
 		expect(result.error).toContain('Expected string, received number')
 	})
 
+	it('appends a tool-specific recovery hint to validation failures', async () => {
+		const r = new ToolRegistry()
+		r.register(
+			makeTool('strict', {
+				inputSchema: z.object({ required: z.string() }),
+				validationErrorHint: 'Retry with {"required":"value"}.',
+			}),
+		)
+		const result = await r.execute('strict', { required: 123 }, makeContext())
+		expect(result.success).toBe(false)
+		expect(result.error).toContain('Required: required: string.')
+		expect(result.error).toContain('Retry with {"required":"value"}.')
+	})
+
 	it('empty-args validation lists required params with descriptions', async () => {
 		const r = new ToolRegistry()
 		r.register(
 			makeTool('needs', {
-				inputSchema: z.object({ q: z.string().describe('the query'), n: z.number() }),
+				inputSchema: z.object({
+					q: z.string().describe('the query'),
+					n: z.number(),
+				}),
 			}),
 		)
 		const result = await r.execute('needs', {}, makeContext())
@@ -458,7 +565,10 @@ describe('ToolRegistry — execute', () => {
 	it('validation hint tolerates a schema it cannot introspect', async () => {
 		const r = new ToolRegistry()
 		const bogusSchema = {
-			safeParse: () => ({ success: false, error: { issues: [{ path: [], message: 'nope' }] } }),
+			safeParse: () => ({
+				success: false,
+				error: { issues: [{ path: [], message: 'nope' }] },
+			}),
 		}
 		r.register(makeTool('weird', { inputSchema: bogusSchema as never }))
 		const result = await r.execute('weird', { a: 1 }, makeContext())
@@ -516,7 +626,11 @@ describe('ToolRegistry — execute', () => {
 			'mutate',
 			{},
 			makeContext({
-				permissionContext: { mode: 'plan', runId: 'run_1', workingDirectory: '/tmp' },
+				permissionContext: {
+					mode: 'plan',
+					runId: 'run_1',
+					workingDirectory: '/tmp',
+				},
 			}),
 		)
 		expect(result.success).toBe(false)