@namzu/sdk 1.3.0 → 1.4.0

package/src/manager/run/persistence.ts

@@ -5,6 +5,7 @@ import { RunDiskStore } from '../../store/run/disk.js'
 import { type CostInfo, type TokenUsage, accumulateTokenUsage } from '../../types/common/index.js'
 import type { RunId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { Message } from '../../types/message/index.js'
+import type { ProviderErrorInfo } from '../../types/provider/index.js'
 import type { CheckpointRunScope, CheckpointStore } from '../../types/run/checkpoint-store.js'
 import type { EmergencySaveData } from '../../types/run/emergency.js'
 import type { Run, RunPersistenceConfig, StopReason } from '../../types/run/index.js'
@@ -164,10 +165,11 @@ export class RunPersistence {
 		this.resolveResult()
 	}
 
-	markFailed(error: string): void {
+	markFailed(error: string, providerError?: ProviderErrorInfo): void {
 		this.run.status = 'failed'
 		this.run.stopReason = 'error'
 		this.run.lastError = error
+		if (providerError) this.run.lastProviderError = providerError
 		this.run.endedAt = Date.now()
 	}
 

package/src/provider/__tests__/errors.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+	ProviderRequestError,
+	bodySaysContextOverflow,
+	classifyProviderHttpStatus,
+	isCallerAbortError,
+	isProviderRequestError,
+	parseRetryAfterMs,
+	providerVendorError,
+} from '../errors.js'
+
+describe('provider error taxonomy', () => {
+	it('classifies only context-specific limit messages as context overflow', () => {
+		expect(bodySaysContextOverflow('input token count exceeds the maximum for this model')).toBe(
+			true,
+		)
+		expect(bodySaysContextOverflow('tool count exceeds the maximum allowed')).toBe(false)
+		expect(bodySaysContextOverflow('reduce the tool list length')).toBe(false)
+	})
+
+	it('does not treat a generic HTTP 413 as model context overflow', () => {
+		expect(classifyProviderHttpStatus(413, 'request body too large at reverse proxy')).toBe(
+			'bad_request',
+		)
+		expect(classifyProviderHttpStatus(413, 'prompt is too long for requested model')).toBe(
+			'context_overflow',
+		)
+	})
+
+	it('parses both Retry-After forms and rejects stale or invalid values', () => {
+		expect(parseRetryAfterMs('2', 0)).toBe(2000)
+		expect(parseRetryAfterMs('Thu, 01 Jan 1970 00:00:05 GMT', 1000)).toBe(4000)
+		expect(parseRetryAfterMs('Thu, 01 Jan 1970 00:00:01 GMT', 1000)).toBeUndefined()
+		expect(parseRetryAfterMs('later', 0)).toBeUndefined()
+	})
+
+	it('drops the vendor object and its non-enumerable cause entirely', () => {
+		const secret = 'sk-FAKE-DO-NOT-LOG'
+		const vendor = new Error(`invalid api key ${secret}`, {
+			cause: new Error(`response body ${secret}`),
+		})
+		Object.assign(vendor, { status: 401 })
+
+		const classified = providerVendorError({
+			providerId: 'test-provider',
+			error: vendor,
+		})
+
+		expect(classified).toMatchObject({
+			name: 'ProviderRequestError',
+			kind: 'auth',
+			status: 401,
+			providerId: 'test-provider',
+		})
+		expect(classified.message).not.toContain(secret)
+		expect('cause' in classified).toBe(false)
+	})
+
+	it('recognizes a caller abort only when that signal actually aborted', () => {
+		const controller = new AbortController()
+		const sdkAbort = Object.assign(new Error('request aborted'), {
+			name: 'APIUserAbortError',
+		})
+
+		expect(isCallerAbortError(sdkAbort, controller.signal)).toBe(false)
+		controller.abort(new Error('user stopped'))
+		expect(isCallerAbortError(sdkAbort, controller.signal)).toBe(true)
+		expect(isCallerAbortError(controller.signal.reason, controller.signal)).toBe(true)
+	})
+
+	it('requires the complete structural contract when SDK copies differ', () => {
+		const classified = new ProviderRequestError({
+			kind: 'server',
+			providerId: 'test-provider',
+		})
+		expect(isProviderRequestError(classified)).toBe(true)
+
+		const impostor = Object.assign(new Error('not classified'), {
+			name: 'ProviderRequestError',
+			kind: 'anything',
+		})
+		expect(isProviderRequestError(impostor)).toBe(false)
+	})
+})

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

@@ -433,6 +433,20 @@ 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(

package/src/registry/tool/execute.ts

@@ -370,10 +370,13 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 						Object.keys(rawInput as Record<string, unknown>).length === 0)
 
 				const requiredHint = describeRequiredInput(tool.inputSchema)
+				const recoveryHint = tool.validationErrorHint?.trim()
+					? ` ${tool.validationErrorHint.trim()}`
+					: ''
 
 				const enrichedMessage = isEmptyInput
-					? `Tool "${toolName}" was called with no arguments. ${requiredHint} Retry the call with the required parameters populated.`
-					: `Validation failed for "${toolName}": ${errorMessage}. ${requiredHint}`
+					? `Tool "${toolName}" was called with no arguments. ${requiredHint}${recoveryHint} Retry the call with the required parameters populated.`
+					: `Validation failed for "${toolName}": ${errorMessage}. ${requiredHint}${recoveryHint}`
 
 				this.log.error(`Tool input validation failed: ${toolName}`, {
 					errors: errorMessage,