@namzu/sdk 1.2.0 → 1.4.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,4 +1,25 @@
-export { ProviderRegistry, UnknownProviderError, DuplicateProviderError } from './registry.js'
+export {
+	ProviderRequestError,
+	isCallerAbortError,
+	isProviderRequestError,
+	classifyProviderHttpStatus,
+	bodySaysContextOverflow,
+	parseRetryAfterMs,
+	providerHttpError,
+	providerVendorError,
+} from './errors.js'
+export type {
+	ProviderErrorInfo,
+	ProviderErrorKind,
+	ProviderRequestErrorInit,
+} from './errors.js'
+export {
+	ProviderRegistry,
+	UnknownProviderError,
+	DuplicateProviderError,
+	LazyProviderLoadError,
+	LazyProviderSyncCreateError,
+} from './registry.js'
 export { MockLLMProvider } from './mock.js'
 export { registerMock, MOCK_CAPABILITIES } from './mock-register.js'
 export {

package/src/provider/registry.ts

@@ -1,13 +1,17 @@
 import type {
 	LLMProvider,
 	LLMProviderConstructor,
+	LazyProviderLoader,
+	LazyProviderModule,
 	ProviderCapabilities,
 	ProviderConfigRegistry,
 	ProviderFactoryConfig,
 	ProviderFactoryResult,
 	ProviderType,
+	RegisterLazyOptions,
 	RegisterOptions,
 } from '../types/provider/index.js'
+import { PERMISSIVE_PROVIDER_CAPABILITIES } from './capabilities.js'
 
 export class UnknownProviderError extends Error {
 	readonly providerType: string
@@ -31,9 +35,99 @@ export class DuplicateProviderError extends Error {
 	}
 }
 
+/**
+ * The loader passed to `ProviderRegistry.registerLazy()` rejected (or
+ * resolved to something without a `create(config)` function). Wraps the
+ * original failure as `cause`. The failed load is NOT cached — the next
+ * `createAsync()` for the type re-invokes the loader, so a transient
+ * failure (network hiccup during a dynamic import) does not permanently
+ * poison the type.
+ */
+export class LazyProviderLoadError extends Error {
+	readonly providerType: string
+
+	constructor(providerType: string, cause: unknown) {
+		const detail = cause instanceof Error ? cause.message : String(cause)
+		super(`Failed to load lazy provider "${providerType}": ${detail}`, { cause })
+		this.name = 'LazyProviderLoadError'
+		this.providerType = providerType
+	}
+}
+
+/**
+ * A synchronous `create()`/`createProvider()` was called for a type
+ * registered via `registerLazy()`. Lazy types are only constructible
+ * through the async path — deterministically, even after the loader has
+ * resolved, so calling code never depends on load-order timing.
+ */
+export class LazyProviderSyncCreateError extends Error {
+	readonly providerType: string
+
+	constructor(providerType: string) {
+		super(
+			`Provider type "${providerType}" is registered lazily; synchronous create()/createProvider() cannot load it. Use ProviderRegistry.createAsync() or createProviderAsync().`,
+		)
+		this.name = 'LazyProviderSyncCreateError'
+		this.providerType = providerType
+	}
+}
+
+interface LazyProviderEntry {
+	loader: LazyProviderLoader<unknown>
+	/** In-flight load shared by concurrent first-creates (dedupe). */
+	loading?: Promise<LazyProviderModule<unknown>>
+	/** Cached module — set only on SUCCESS, so failures retry. */
+	module?: LazyProviderModule<unknown>
+}
+
 // Module-private state. Only the exported functions below can read/mutate.
 const providers = new Map<string, LLMProviderConstructor<unknown>>()
 const capabilities = new Map<string, ProviderCapabilities>()
+const lazyProviders = new Map<string, LazyProviderEntry>()
+
+async function loadLazyModule(
+	type: string,
+	entry: LazyProviderEntry,
+): Promise<LazyProviderModule<unknown>> {
+	if (entry.module) {
+		return entry.module
+	}
+	let inflight = entry.loading
+	if (!inflight) {
+		// Promise.resolve().then(...) also catches loaders that throw synchronously.
+		inflight = Promise.resolve()
+			.then(() => entry.loader())
+			.then((mod) => {
+				if (typeof mod?.create !== 'function') {
+					throw new TypeError(
+						'loader resolved to a value without a create(config) function — map your dynamic import to { create: (config) => new Provider(config) }',
+					)
+				}
+				return mod
+			})
+		entry.loading = inflight
+	}
+	try {
+		const mod = await inflight
+		entry.module = mod
+		if (entry.loading === inflight) {
+			entry.loading = undefined
+		}
+		// The loaded module's declaration is authoritative at the type level:
+		// it replaces any registration-time hint for future getCapabilities().
+		if (mod.capabilities) {
+			capabilities.set(type, mod.capabilities)
+		}
+		return mod
+	} catch (cause) {
+		// Clear only OUR in-flight promise; a retry started by another caller
+		// after an earlier failure must not be dropped.
+		if (entry.loading === inflight) {
+			entry.loading = undefined
+		}
+		throw new LazyProviderLoadError(type, cause)
+	}
+}
 
 /**
  * Central registry for LLM providers.
@@ -56,6 +150,23 @@ const capabilities = new Map<string, ProviderCapabilities>()
  *   region: 'us-east-1',
  * })
  * ```
+ *
+ * Hosts that must not eagerly bundle every provider client register a
+ * LOADER instead and construct through the async path:
+ *
+ * @example
+ * ```ts
+ * ProviderRegistry.registerLazy(
+ *   'anthropic',
+ *   async () => {
+ *     const m = await import('@namzu/anthropic')
+ *     return { create: (c) => new m.AnthropicProvider(c), capabilities: m.ANTHROPIC_CAPABILITIES }
+ *   },
+ *   { capabilities: { supportsTools: true, supportsStreaming: true, supportsFunctionCalling: true } },
+ * )
+ *
+ * const { provider } = await ProviderRegistry.createAsync({ type: 'anthropic', apiKey })
+ * ```
  */
 export class ProviderRegistry {
 	static register<K extends ProviderType>(
@@ -64,46 +175,129 @@ export class ProviderRegistry {
 		caps: ProviderCapabilities,
 		options?: RegisterOptions,
 	): void {
-		if (providers.has(type) && !options?.replace) {
+		if ((providers.has(type) || lazyProviders.has(type)) && !options?.replace) {
 			throw new DuplicateProviderError(type)
 		}
+		lazyProviders.delete(type)
 		providers.set(type, ctor as LLMProviderConstructor<unknown>)
 		capabilities.set(type, caps)
 	}
 
+	/**
+	 * Register a provider type WITHOUT importing its implementation. The
+	 * loader is not invoked here; the first `createAsync()` for the type
+	 * awaits it, validates the resolved `{ create }` module, and caches it.
+	 * Subsequent creates reuse the cached factory. Only SUCCESS is cached:
+	 * a rejected load surfaces as `LazyProviderLoadError` and the next
+	 * `createAsync()` retries the loader. Concurrent first-creates share a
+	 * single in-flight load.
+	 *
+	 * Capability precedence (weakest first):
+	 * 1. `options.capabilities` — pre-load HINT so `getCapabilities(type)`
+	 *    answers without loading (absent hint ⇒ permissive default, matching
+	 *    `resolveProviderCapabilities`'s treatment of undeclared providers).
+	 * 2. the loaded module's `capabilities` — replaces the hint on load.
+	 * 3. the constructed instance's own `LLMProvider.capabilities` — the
+	 *    query runtime negotiates against the INSTANCE
+	 *    (`resolveProviderCapabilities(provider)`), so if it differs from
+	 *    both of the above, the instance wins where it matters.
+	 *
+	 * Lazy types are deliberately NOT constructible via the sync
+	 * `create()`/`createProvider()` (throws `LazyProviderSyncCreateError`),
+	 * even after the loader has resolved — sync behavior must not depend on
+	 * whether some earlier call happened to load the module.
+	 */
+	static registerLazy<K extends ProviderType>(
+		type: K,
+		loader: LazyProviderLoader<ProviderConfigRegistry[K]>,
+		options?: RegisterLazyOptions,
+	): void {
+		if ((providers.has(type) || lazyProviders.has(type)) && !options?.replace) {
+			throw new DuplicateProviderError(type)
+		}
+		providers.delete(type)
+		capabilities.delete(type)
+		lazyProviders.set(type, { loader: loader as LazyProviderLoader<unknown> })
+		if (options?.capabilities) {
+			capabilities.set(type, options.capabilities)
+		}
+	}
+
 	static create(config: ProviderFactoryConfig): ProviderFactoryResult {
 		const provider = ProviderRegistry.createProvider(config)
 		const caps = ProviderRegistry.getCapabilities(config.type)
 		return { provider, capabilities: caps }
 	}
 
+	/**
+	 * Async twin of `create()`. Works for BOTH eager and lazy registrations,
+	 * so hosts can use one code path; for lazy types it performs the
+	 * load-on-first-use described on `registerLazy()`.
+	 */
+	static async createAsync(config: ProviderFactoryConfig): Promise<ProviderFactoryResult> {
+		const provider = await ProviderRegistry.createProviderAsync(config)
+		// Read capabilities AFTER construction so a lazily-loaded module's
+		// authoritative declaration (set during load) is what gets returned.
+		const caps = ProviderRegistry.getCapabilities(config.type)
+		return { provider, capabilities: caps }
+	}
+
 	static createProvider(config: ProviderFactoryConfig): LLMProvider {
 		const Ctor = providers.get(config.type)
 		if (!Ctor) {
+			if (lazyProviders.has(config.type)) {
+				throw new LazyProviderSyncCreateError(config.type)
+			}
 			throw new UnknownProviderError(config.type)
 		}
 		return new Ctor(config)
 	}
 
+	static async createProviderAsync(config: ProviderFactoryConfig): Promise<LLMProvider> {
+		const Ctor = providers.get(config.type)
+		if (Ctor) {
+			return new Ctor(config)
+		}
+		const entry = lazyProviders.get(config.type)
+		if (!entry) {
+			throw new UnknownProviderError(config.type)
+		}
+		const mod = await loadLazyModule(config.type, entry)
+		return mod.create(config)
+	}
+
+	/**
+	 * Type-level capabilities. For a lazily-registered type this answers
+	 * WITHOUT invoking the loader: the registration hint if one was given,
+	 * otherwise the permissive default (assume everything — consistent with
+	 * how `resolveProviderCapabilities` treats an undeclared provider). Once
+	 * loaded, a module-shipped declaration replaces the hint. Note the query
+	 * runtime negotiates against the constructed INSTANCE's own
+	 * `capabilities`, which wins over anything stored here.
+	 */
 	static getCapabilities(type: string): ProviderCapabilities {
 		const caps = capabilities.get(type)
-		if (!caps) {
-			throw new UnknownProviderError(type)
+		if (caps) {
+			return caps
+		}
+		if (lazyProviders.has(type)) {
+			return PERMISSIVE_PROVIDER_CAPABILITIES
 		}
-		return caps
+		throw new UnknownProviderError(type)
 	}
 
 	static isSupported(type: string): type is ProviderType {
-		return providers.has(type)
+		return providers.has(type) || lazyProviders.has(type)
 	}
 
 	static unregister(type: ProviderType): boolean {
 		capabilities.delete(type)
-		return providers.delete(type)
+		const hadLazy = lazyProviders.delete(type)
+		return providers.delete(type) || hadLazy
 	}
 
 	static listTypes(): ProviderType[] {
-		return Array.from(providers.keys()) as ProviderType[]
+		return Array.from(new Set([...providers.keys(), ...lazyProviders.keys()])) as ProviderType[]
 	}
 }
 
@@ -115,4 +309,5 @@ export class ProviderRegistry {
 export function __resetProviderRegistryInternal(): void {
 	providers.clear()
 	capabilities.clear()
+	lazyProviders.clear()
 }