@db3.ai/app 0.1.0-beta.1

package/package.json

@@ -0,0 +1,290 @@
+{
+	"name": "@db3.ai/app",
+	"version": "0.1.0-beta.1",
+	"description": "A typed backend application framework with service-owned runtime modules and behavioural contracts.",
+	"license": "MIT",
+	"type": "module",
+	"homepage": "https://db3.ai/",
+	"keywords": [
+		"db3",
+		"typescript",
+		"backend",
+		"framework",
+		"active-record",
+		"queue",
+		"ssr"
+	],
+	"engines": {
+		"node": ">=20"
+	},
+	"bin": {
+		"db3-agents": "bin/db3-agents.mjs",
+		"db3": "bin/db3.mjs"
+	},
+	"exports": {
+		"./ai": {
+			"types": "./dist/ai/index.d.ts",
+			"import": "./dist/ai/index.js",
+			"default": "./dist/ai/index.js"
+		},
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./agent-instructions": "./agent-instructions.md",
+		"./auth": {
+			"types": "./dist/auth/index.d.ts",
+			"import": "./dist/auth/index.js",
+			"default": "./dist/auth/index.js"
+		},
+		"./auth/password-hash": {
+			"types": "./dist/auth/passwordHash.d.ts",
+			"import": "./dist/auth/passwordHash.js",
+			"default": "./dist/auth/passwordHash.js"
+		},
+		"./cache": {
+			"types": "./dist/cache/index.d.ts",
+			"import": "./dist/cache/index.js",
+			"default": "./dist/cache/index.js"
+		},
+		"./cli": {
+			"types": "./dist/cli/index.d.ts",
+			"import": "./dist/cli/index.js",
+			"default": "./dist/cli/index.js"
+		},
+		"./db": {
+			"types": "./dist/db/index.d.ts",
+			"import": "./dist/db/index.js",
+			"default": "./dist/db/index.js"
+		},
+		"./db/commands": {
+			"types": "./dist/db/commands/index.d.ts",
+			"import": "./dist/db/commands/index.js",
+			"default": "./dist/db/commands/index.js"
+		},
+		"./db/ActiveProjection": {
+			"types": "./dist/db/ActiveProjection.d.ts",
+			"import": "./dist/db/ActiveProjection.js",
+			"default": "./dist/db/ActiveProjection.js"
+		},
+		"./db/ActiveRecord": {
+			"types": "./dist/db/ActiveRecord.d.ts",
+			"import": "./dist/db/ActiveRecord.js",
+			"default": "./dist/db/ActiveRecord.js"
+		},
+		"./db/ActiveQueryBuilder": {
+			"types": "./dist/db/ActiveQueryBuilder.d.ts",
+			"import": "./dist/db/ActiveQueryBuilder.js",
+			"default": "./dist/db/ActiveQueryBuilder.js"
+		},
+		"./db/Database": {
+			"types": "./dist/db/Database.d.ts",
+			"import": "./dist/db/Database.js",
+			"default": "./dist/db/Database.js"
+		},
+		"./db/FieldType": {
+			"types": "./dist/db/FieldType.d.ts",
+			"import": "./dist/db/FieldType.js",
+			"default": "./dist/db/FieldType.js"
+		},
+		"./db/connection": {
+			"types": "./dist/db/connection.d.ts",
+			"import": "./dist/db/connection.js",
+			"default": "./dist/db/connection.js"
+		},
+		"./db/dialects": {
+			"types": "./dist/db/dialects/index.d.ts",
+			"import": "./dist/db/dialects/index.js",
+			"default": "./dist/db/dialects/index.js"
+		},
+		"./db/fields": {
+			"types": "./dist/db/fields/index.d.ts",
+			"import": "./dist/db/fields/index.js",
+			"default": "./dist/db/fields/index.js"
+		},
+		"./db/fields/*": {
+			"types": "./dist/db/fields/*.d.ts",
+			"import": "./dist/db/fields/*.js",
+			"default": "./dist/db/fields/*.js"
+		},
+		"./db/migrations": {
+			"types": "./dist/db/migrations/index.d.ts",
+			"import": "./dist/db/migrations/index.js",
+			"default": "./dist/db/migrations/index.js"
+		},
+		"./db/queryMonitor": {
+			"types": "./dist/db/queryMonitor.d.ts",
+			"import": "./dist/db/queryMonitor.js",
+			"default": "./dist/db/queryMonitor.js"
+		},
+		"./db/test/db": {
+			"types": "./dist/db/test/db.d.ts",
+			"import": "./dist/db/test/db.js",
+			"default": "./dist/db/test/db.js"
+		},
+		"./config": {
+			"types": "./dist/config/index.d.ts",
+			"import": "./dist/config/index.js",
+			"default": "./dist/config/index.js"
+		},
+		"./events": {
+			"types": "./dist/events/index.d.ts",
+			"import": "./dist/events/index.js",
+			"default": "./dist/events/index.js"
+		},
+		"./flows": {
+			"types": "./dist/flows/index.d.ts",
+			"import": "./dist/flows/index.js",
+			"default": "./dist/flows/index.js"
+		},
+		"./flows/blocks": {
+			"types": "./dist/flows/blocks/index.d.ts",
+			"import": "./dist/flows/blocks/index.js",
+			"default": "./dist/flows/blocks/index.js"
+		},
+		"./url": {
+			"types": "./dist/url/index.d.ts",
+			"import": "./dist/url/index.js",
+			"default": "./dist/url/index.js"
+		},
+		"./mail": {
+			"types": "./dist/mail/index.d.ts",
+			"import": "./dist/mail/index.js",
+			"default": "./dist/mail/index.js"
+		},
+		"./logging": {
+			"types": "./dist/logging/index.d.ts",
+			"import": "./dist/logging/index.js",
+			"default": "./dist/logging/index.js"
+		},
+		"./media": {
+			"types": "./dist/media/index.d.ts",
+			"import": "./dist/media/index.js",
+			"default": "./dist/media/index.js"
+		},
+		"./media/image": {
+			"types": "./dist/media/image/index.d.ts",
+			"import": "./dist/media/image/index.js",
+			"default": "./dist/media/image/index.js"
+		},
+		"./queue": {
+			"types": "./dist/queue/index.d.ts",
+			"import": "./dist/queue/index.js",
+			"default": "./dist/queue/index.js"
+		},
+		"./queue/commands": {
+			"types": "./dist/queue/commands/index.d.ts",
+			"import": "./dist/queue/commands/index.js",
+			"default": "./dist/queue/commands/index.js"
+		},
+		"./scheduler": {
+			"types": "./dist/scheduler/index.d.ts",
+			"import": "./dist/scheduler/index.js",
+			"default": "./dist/scheduler/index.js"
+		},
+		"./security": {
+			"types": "./dist/security/index.d.ts",
+			"import": "./dist/security/index.js",
+			"default": "./dist/security/index.js"
+		},
+		"./serialization": {
+			"types": "./dist/serialization/index.d.ts",
+			"import": "./dist/serialization/index.js",
+			"default": "./dist/serialization/index.js"
+		},
+		"./server": {
+			"types": "./dist/server/index.d.ts",
+			"import": "./dist/server/index.js",
+			"default": "./dist/server/index.js"
+		},
+		"./ssr": {
+			"types": "./dist/ssr/index.d.ts",
+			"import": "./dist/ssr/index.js",
+			"default": "./dist/ssr/index.js"
+		},
+		"./ssr/fastify": {
+			"types": "./dist/ssr/fastify/index.d.ts",
+			"import": "./dist/ssr/fastify/index.js",
+			"default": "./dist/ssr/fastify/index.js"
+		},
+		"./ssr/vite": {
+			"types": "./dist/ssr/vite/index.d.ts",
+			"import": "./dist/ssr/vite/index.js",
+			"default": "./dist/ssr/vite/index.js"
+		},
+		"./storage": {
+			"types": "./dist/storage/index.d.ts",
+			"import": "./dist/storage/index.js",
+			"default": "./dist/storage/index.js"
+		},
+		"./validation": {
+			"types": "./dist/validation/index.d.ts",
+			"import": "./dist/validation/index.js",
+			"default": "./dist/validation/index.js"
+		}
+	},
+	"dependencies": {
+		"tsx": "^4.22.4",
+		"openai": "^6.44.0",
+		"@aws-sdk/client-s3": "^3.1077.0",
+		"@flystorage/aws-s3": "^1.2.0",
+		"@flystorage/file-storage": "^1.2.2",
+		"@flystorage/local-fs": "^1.2.0",
+		"@keyv/redis": "^5.1.6",
+		"@db3.ai/pure": "0.1.0-beta.1",
+		"@redis/client": "^6.1.0",
+		"cache-manager": "^7.2.9",
+		"cacheable": "^2.5.0",
+		"dotenv": "^17.4.2",
+		"knex": "^3.2.10",
+		"mysql2": "^3.22.5",
+		"pino": "^10.3.1",
+		"pino-abstract-transport": "^3.0.0",
+		"sharp": "^0.35.4",
+		"thread-stream": "^4.0.0",
+		"zod": "^4.4.3",
+		"@openai/agents": "0.12.1"
+	},
+	"peerDependencies": {
+		"@fastify/middie": "^9.3.3",
+		"@fastify/static": "^10.1.3",
+		"fastify": "^5.11.3",
+		"vite": "^8.2.1"
+	},
+	"peerDependenciesMeta": {
+		"@fastify/middie": {
+			"optional": true
+		},
+		"@fastify/static": {
+			"optional": true
+		},
+		"fastify": {
+			"optional": true
+		},
+		"vite": {
+			"optional": true
+		}
+	},
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist",
+		"README.md",
+		"agent-instructions.md",
+		"bin",
+		"templates",
+		"src",
+		"LICENSE"
+	],
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/",
+		"provenance": true
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/db3ai/framework.git",
+		"directory": "packages/app"
+	}
+}

package/src/ai/AIErrors.ts

@@ -0,0 +1,46 @@
+/**
+ * Raised when an AI operation needs provider credentials but none are configured.
+ */
+export class AIConfigurationError extends Error {
+	/** Creates a missing-provider-configuration error. */
+	constructor(message = 'Set OPENAI_API_KEY before using AI features.') {
+		super(message);
+		this.name = 'AIConfigurationError';
+	}
+}
+
+/**
+ * Raised when the provider rejects a request or returns a payload without text.
+ */
+export class AIRequestError extends Error {
+	/**
+	 * Creates a provider request failure.
+	 *
+	 * @param message - Human-readable provider failure message.
+	 * @param code - Stable provider error code, when supplied.
+	 */
+	constructor(
+		message = 'The AI provider did not return a valid response.',
+		readonly code: string | null = null,
+	) {
+		super(message);
+		this.name = 'AIRequestError';
+	}
+}
+
+/**
+ * Raised when the application allowance hook rejects an AI request.
+ */
+export class AIAllowanceExceededError extends Error {
+	/** Stable public failure code; applications may specialize it for their own allowance UI. */
+	readonly publicCode: string = 'ai_allowance_exceeded';
+	/**
+	 * Create an allowance failure.
+	 *
+	 * @param message - Public error message for the denied request.
+	 */
+	constructor(message = 'AI allowance has been reached for this period.') {
+		super(message);
+		this.name = 'AIAllowanceExceededError';
+	}
+}

package/src/ai/AIFailover.ts

@@ -0,0 +1,101 @@
+import { AIRateLimitDeferredError } from './AIRateLimiter.js';
+import { openAIProviderError, isOpenAIQuotaError } from './OpenAIProviderError.js';
+
+const FAILOVERABLE_STATUS_CODES = new Set([408, 409, 429]);
+
+const FAILOVERABLE_ERROR_CODES = new Set([
+	'rate_limit_exceeded',
+	'insufficient_quota',
+	'billing_hard_limit_reached',
+	'overloaded',
+	'overloaded_error',
+	'server_error',
+	'service_unavailable',
+]);
+
+const NETWORK_ERROR_NAMES = new Set([
+	'AbortError',
+	'TimeoutError',
+	'APIConnectionError',
+	'APIConnectionTimeoutError',
+	'ConnectTimeoutError',
+	'FetchError',
+]);
+
+const NETWORK_ERROR_CODES = new Set([
+	'ETIMEDOUT',
+	'ECONNRESET',
+	'ECONNREFUSED',
+	'ENOTFOUND',
+	'EAI_AGAIN',
+	'EPIPE',
+	'UND_ERR_CONNECT_TIMEOUT',
+	'UND_ERR_HEADERS_TIMEOUT',
+	'UND_ERR_BODY_TIMEOUT',
+	'UND_ERR_SOCKET',
+]);
+
+/**
+ * Decides whether a provider HTTP response should fail over to the next provider.
+ *
+ * Failover is reserved for transient availability problems and exhausted
+ * account capacity: rate limits, overload, 5xx, timeouts, and quota. Request
+ * problems such as validation or authentication failures stay terminal because
+ * retrying them on another provider repeats the same failure at extra cost.
+ *
+ * @param status - HTTP response status.
+ * @param payload - Parsed provider response payload.
+ * @returns True when the next provider in the chain should be attempted.
+ */
+export function isFailoverableResponse(status: number, payload: unknown): boolean {
+	if (FAILOVERABLE_STATUS_CODES.has(status) || status >= 500) return true;
+	if (isOpenAIQuotaError(payload)) return true;
+
+	const code = openAIProviderError(payload).code;
+
+	return code !== null && FAILOVERABLE_ERROR_CODES.has(code);
+}
+
+/**
+ * Decides whether a thrown provider or SDK failure should fail over.
+ *
+ * Local rate-limit deferrals count as failoverable because a full local bucket
+ * for one provider says nothing about the capacity of the next provider.
+ * Streaming SDK failures may carry a provider code without an HTTP status, so
+ * classification never relies on status alone.
+ *
+ * @param error - Unknown thrown value from a provider call or SDK run.
+ * @returns True when the next provider in the chain should be attempted.
+ */
+export function isFailoverableFailure(error: unknown): boolean {
+	if (error instanceof AIRateLimitDeferredError) return true;
+	if (isNetworkFailure(error)) return true;
+
+	const details = openAIProviderError(error);
+
+	if (details.code !== null && FAILOVERABLE_ERROR_CODES.has(details.code)) return true;
+	if (details.status !== null && (FAILOVERABLE_STATUS_CODES.has(details.status) || details.status >= 500)) return true;
+
+	return false;
+}
+
+/**
+ * Detects network, DNS, and timeout failures from fetch and SDK clients.
+ *
+ * Undici wraps socket errors inside `TypeError: fetch failed` with the real
+ * failure on `cause`, so the check walks the cause chain.
+ *
+ * @param error - Unknown thrown value.
+ * @returns True when the failure happened before a provider response arrived.
+ */
+function isNetworkFailure(error: unknown, depth = 0): boolean {
+	if ((!(error instanceof Error) && !(error instanceof DOMException)) || depth > 4) return false;
+	if (NETWORK_ERROR_NAMES.has(error.name)) return true;
+	if (error instanceof TypeError && error.message.includes('fetch failed')) return true;
+
+	const code = (error as Error & { code?: unknown }).code;
+
+	if (typeof code === 'string' && NETWORK_ERROR_CODES.has(code)) return true;
+
+	return isNetworkFailure(error.cause, depth + 1);
+}

package/src/ai/AIProviders.ts

@@ -0,0 +1,228 @@
+import type { AIProviderConfig, AIProviderAttempt, AIProviderAttemptFailure, ResolvedOpenAIConnection, ResolveProviderChainInput } from './contracts/Providers';
+export type { AIProviderConfig, AIProviderAttempt, AIProviderAttemptFailure, ResolvedOpenAIConnection, ResolveProviderChainInput } from './contracts/Providers';
+import { AI_PROVIDER, type AIProvider, type AIProviderSelection } from './contracts/AI.js';
+import { AIConfigurationError } from './AIErrors.js';
+
+const AI_PROVIDER_CONFIG: Record<AIProvider, AIProviderConfig> = {
+	[AI_PROVIDER.openai]: {
+		apiKeyEnv: 'OPENAI_API_KEY',
+		baseUrlEnv: 'OPENAI_BASE_URL',
+		modelEnv: null,
+		defaultBaseUrl: 'https://api.openai.com/v1',
+		supportsResponsesApi: true,
+	},
+	[AI_PROVIDER.openrouter]: {
+		apiKeyEnv: 'OPENROUTER_API_KEY',
+		baseUrlEnv: 'OPENROUTER_BASE_URL',
+		modelEnv: 'OPENROUTER_MODEL',
+		defaultBaseUrl: 'https://openrouter.ai/api/v1',
+		supportsResponsesApi: true,
+	},
+	[AI_PROVIDER.groq]: {
+		apiKeyEnv: 'GROQ_API_KEY',
+		baseUrlEnv: 'GROQ_BASE_URL',
+		modelEnv: 'GROQ_MODEL',
+		defaultBaseUrl: 'https://api.groq.com/openai/v1',
+		supportsResponsesApi: false,
+	},
+	[AI_PROVIDER.xai]: {
+		apiKeyEnv: 'XAI_API_KEY',
+		baseUrlEnv: 'XAI_BASE_URL',
+		modelEnv: 'XAI_MODEL',
+		defaultBaseUrl: 'https://api.x.ai/v1',
+		supportsResponsesApi: false,
+	},
+	[AI_PROVIDER.deepseek]: {
+		apiKeyEnv: 'DEEPSEEK_API_KEY',
+		baseUrlEnv: 'DEEPSEEK_BASE_URL',
+		modelEnv: 'DEEPSEEK_MODEL',
+		defaultBaseUrl: 'https://api.deepseek.com/v1',
+		supportsResponsesApi: false,
+	},
+};
+
+/**
+ * Resolves an ordered provider selection into fully configured attempts.
+ *
+ * Providers without an API key, or non-OpenAI providers without a model, are
+ * skipped so a half-configured backup can never break the primary path. The
+ * OpenAI entry keeps using the AI service's resolved key, base URL, and model.
+ *
+ * @param input - Selection plus the resolved OpenAI connection.
+ * @returns Ordered attempts to try in sequence.
+ * @throws AIConfigurationError when no provider in the selection is usable.
+ */
+export function resolveProviderChain(input: ResolveProviderChainInput): AIProviderAttempt[] {
+	const entries = normalizeSelection(input.selection);
+	const disabled = providerListFromEnvironment('AI_PROVIDER_DISABLED');
+	const attempts: AIProviderAttempt[] = [];
+	let sawDisabled = false;
+
+	for (const [provider, model] of entries) {
+		if (disabled.includes(provider)) {
+			sawDisabled = true;
+
+			continue;
+		}
+
+		const attempt = resolveAttempt(provider, model, input.openai);
+
+		if (attempt) attempts.push(attempt);
+	}
+
+	if (attempts.length === 0) {
+		throw new AIConfigurationError(sawDisabled
+			? 'No usable AI provider remains: every provider in the selection is disabled by AI_PROVIDER_DISABLED or unconfigured.'
+			: undefined);
+	}
+
+	return attempts;
+}
+
+/**
+ * Reads the app-wide default provider chain from AI_PROVIDER_CHAIN.
+ *
+ * @returns Ordered provider list, or null when the variable is unset.
+ * @throws AIConfigurationError when the variable names an unknown provider.
+ */
+export function providerChainFromEnvironment(): AIProvider[] | null {
+	const chain = providerListFromEnvironment('AI_PROVIDER_CHAIN');
+
+	return chain.length > 0 ? chain : null;
+}
+
+/**
+ * Returns a synthetic failoverable outage for providers listed in AI_PROVIDER_OUTAGE.
+ *
+ * This is a development and testing toggle: listed providers stay in the
+ * resolved chain but every attempt fails immediately with a 503-style error
+ * that the failover classifier treats as failoverable. That exercises the real
+ * failover path, attempt auditing, and terminal behavior when no backup is
+ * configured. Use AI_PROVIDER_DISABLED instead to skip a provider entirely.
+ *
+ * @param provider - Provider about to be attempted.
+ * @returns Error to throw in place of the provider call, or null.
+ */
+export function simulatedProviderOutage(provider: AIProvider): Error | null {
+	if (!providerListFromEnvironment('AI_PROVIDER_OUTAGE').includes(provider)) return null;
+
+	return Object.assign(new Error(`Simulated outage for AI provider ${provider} (AI_PROVIDER_OUTAGE).`), {
+		code: 'service_unavailable',
+		status: 503,
+	});
+}
+
+/**
+ * Parses a comma-separated provider list environment variable.
+ *
+ * @param name - Environment variable name.
+ * @returns Ordered provider list, empty when the variable is unset.
+ * @throws AIConfigurationError when the variable names an unknown provider.
+ */
+function providerListFromEnvironment(name: string): AIProvider[] {
+	const value = process.env[name]?.trim();
+
+	if (!value) return [];
+
+	return value.split(',').map(part => {
+		const provider = part.trim();
+
+		if (!isKnownProvider(provider)) {
+			throw new AIConfigurationError(`Unknown AI provider "${provider}" in ${name}.`);
+		}
+
+		return provider;
+	});
+}
+
+/**
+ * Normalizes any selection shape into ordered provider/model pairs.
+ *
+ * @param selection - Provider selection, or null for the OpenAI default.
+ * @returns Ordered pairs where a null model means "use the provider default".
+ * @throws AIConfigurationError when the selection names an unknown provider.
+ */
+function normalizeSelection(selection: AIProviderSelection | null): Array<[AIProvider, string | null]> {
+	if (!selection) return [[AI_PROVIDER.openai, null]];
+
+	if (typeof selection === 'string') {
+		assertKnownProvider(selection);
+
+		return [[selection, null]];
+	}
+
+	if (Array.isArray(selection)) {
+		if (selection.length === 0) return [[AI_PROVIDER.openai, null]];
+
+		return selection.map(provider => {
+			assertKnownProvider(provider);
+
+			return [provider, null];
+		});
+	}
+
+	const entries = Object.entries(selection) as Array<[string, string]>;
+
+	if (entries.length === 0) return [[AI_PROVIDER.openai, null]];
+
+	return entries.map(([provider, model]) => {
+		assertKnownProvider(provider);
+
+		return [provider, model];
+	});
+}
+
+/**
+ * Resolves credentials and model for one provider entry.
+ *
+ * @param provider - Known provider id.
+ * @param model - Explicit model from a record selection, or null.
+ * @param openai - Resolved OpenAI connection for the openai entry.
+ * @returns Configured attempt, or null when the provider is not usable.
+ */
+function resolveAttempt(
+	provider: AIProvider,
+	model: string | null,
+	openai: ResolvedOpenAIConnection,
+): AIProviderAttempt | null {
+	const config = AI_PROVIDER_CONFIG[provider];
+	const isOpenAI = provider === AI_PROVIDER.openai;
+	const apiKey = isOpenAI ? openai.apiKey : (process.env[config.apiKeyEnv] ?? '');
+	const baseUrl = isOpenAI
+		? openai.baseUrl
+		: (process.env[config.baseUrlEnv] || config.defaultBaseUrl).replace(/\/+$/g, '');
+	const resolvedModel = model
+		|| (isOpenAI ? openai.model : (config.modelEnv ? process.env[config.modelEnv] : undefined))
+		|| null;
+
+	if (!apiKey || !resolvedModel) return null;
+
+	return {
+		provider,
+		model: resolvedModel,
+		apiKey,
+		baseUrl,
+		supportsResponsesApi: config.supportsResponsesApi,
+	};
+}
+
+/**
+ * Narrows an arbitrary string to a known provider id.
+ *
+ * @param value - Candidate provider id.
+ * @returns True when the value is a registered provider.
+ */
+function isKnownProvider(value: string): value is AIProvider {
+	return Object.prototype.hasOwnProperty.call(AI_PROVIDER_CONFIG, value);
+}
+
+/**
+ * Throws a configuration error for unknown provider ids in a selection.
+ *
+ * @param value - Candidate provider id.
+ */
+function assertKnownProvider(value: string): asserts value is AIProvider {
+	if (!isKnownProvider(value)) {
+		throw new AIConfigurationError(`Unknown AI provider "${value}" in provider selection.`);
+	}
+}

package/src/ai/AIQuotaDeferredError.ts

@@ -0,0 +1,26 @@
+import { QueueRetryLaterError } from '@db3.ai/app/queue';
+
+/**
+ * Queue-compatible deferral raised while OpenAI account quota is unavailable.
+ */
+export class AIQuotaDeferredError extends QueueRetryLaterError {
+	/**
+	 * Creates one bounded quota deferral.
+	 *
+	 * @param delaySeconds - Seconds before the queued job should retry.
+	 * @param retryAt - Absolute time of the scheduled retry.
+	 * @param retryUntil - Absolute time after which quota retries become terminal.
+	 * @param deferralCount - Number of quota deferrals recorded for this request.
+	 * @param message - Provider failure message.
+	 */
+	constructor(
+		delaySeconds: number,
+		readonly retryAt: Date,
+		readonly retryUntil: Date,
+		readonly deferralCount: number,
+		message: string,
+	) {
+		super(delaySeconds, message);
+		this.name = 'AIQuotaDeferredError';
+	}
+}