@db3.ai/app 0.1.0-beta.1

package/src/ai/Models.ts

@@ -0,0 +1,373 @@
+import type { AIModelPricing, AIImageModelPricing, AIRequestCostUsage, AIRequestCostUsageEntry, AIImageRequestCostUsage, AIHostedToolUsage, AIHostedToolCost } from './contracts/Pricing';
+export type { AIModelPricing, AIImageModelPricing, AIRequestCostUsage, AIRequestCostUsageEntry, AIImageRequestCostUsage, AIHostedToolUsage, AIHostedToolCost } from './contracts/Pricing';
+
+/**
+ * OpenAI Standard processing prices in USD, verified on 2026-09-11.
+ *
+ * Used to estimate request cost at write time; stored historical costs are not
+ * recalculated. Excludes regional processing surcharges and other service tiers.
+ *
+ * @see https://developers.openai.com/api/docs/pricing
+ */
+export const AI_MODEL_PRICING: Record<string, AIModelPricing> = {
+	'gpt-6-astra': {
+		inputUSDPer1M: 10.00,
+		cachedInputUSDPer1M: 1.00,
+		outputUSDPer1M: 50.00,
+		cacheWriteInputMultiplier: 1.25,
+		longContextInputTokenThreshold: 272_000,
+		longContextInputMultiplier: 2,
+		longContextOutputMultiplier: 1.5,
+	},
+	// Promotional rates available at least through 2026-11-21; recheck before changing.
+	'gpt-5.6-sol': {
+		inputUSDPer1M: 4.00,
+		cachedInputUSDPer1M: 0.40,
+		outputUSDPer1M: 20.00,
+		cacheWriteInputMultiplier: 1.25,
+		longContextInputTokenThreshold: 272_000,
+		longContextInputMultiplier: 2,
+		longContextOutputMultiplier: 1.5,
+	},
+	'gpt-5.6-terra': {
+		inputUSDPer1M: 2.00,
+		cachedInputUSDPer1M: 0.20,
+		outputUSDPer1M: 12.00,
+		cacheWriteInputMultiplier: 1.25,
+		longContextInputTokenThreshold: 272_000,
+		longContextInputMultiplier: 2,
+		longContextOutputMultiplier: 1.5,
+	},
+	'gpt-5.6-luna': {
+		inputUSDPer1M: 0.20,
+		cachedInputUSDPer1M: 0.02,
+		outputUSDPer1M: 1.20,
+		cacheWriteInputMultiplier: 1.25,
+		longContextInputTokenThreshold: 272_000,
+		longContextInputMultiplier: 2,
+		longContextOutputMultiplier: 1.5,
+	},
+	'gpt-5.5': {
+		inputUSDPer1M: 5.00,
+		cachedInputUSDPer1M: 0.50,
+		outputUSDPer1M: 30.00,
+		longContextInputTokenThreshold: 272_000,
+		longContextInputMultiplier: 2,
+		longContextOutputMultiplier: 1.5,
+	},
+	'gpt-5.5-pro': {
+		inputUSDPer1M: 30.00,
+		cachedInputUSDPer1M: null,
+		outputUSDPer1M: 180.00,
+		longContextInputTokenThreshold: 272_000,
+		longContextInputMultiplier: 2,
+		longContextOutputMultiplier: 1.5,
+	},
+	'gpt-5.4': {
+		inputUSDPer1M: 2.50,
+		cachedInputUSDPer1M: 0.25,
+		outputUSDPer1M: 15.00,
+		longContextInputTokenThreshold: 272_000,
+		longContextInputMultiplier: 2,
+		longContextOutputMultiplier: 1.5,
+	},
+	'gpt-5.4-mini': {
+		inputUSDPer1M: 0.75,
+		cachedInputUSDPer1M: 0.075,
+		outputUSDPer1M: 4.50,
+	},
+	'gpt-5.4-nano': {
+		inputUSDPer1M: 0.20,
+		cachedInputUSDPer1M: 0.02,
+		outputUSDPer1M: 1.25,
+	},
+	'gpt-5.4-pro': {
+		inputUSDPer1M: 30.00,
+		cachedInputUSDPer1M: null,
+		outputUSDPer1M: 180.00,
+		longContextInputTokenThreshold: 272_000,
+		longContextInputMultiplier: 2,
+		longContextOutputMultiplier: 1.5,
+	},
+	'text-embedding-3-small': {
+		inputUSDPer1M: 0.02,
+		cachedInputUSDPer1M: null,
+		outputUSDPer1M: null,
+	},
+	'text-embedding-3-large': {
+		inputUSDPer1M: 0.13,
+		cachedInputUSDPer1M: null,
+		outputUSDPer1M: null,
+	},
+	'text-embedding-ada-002': {
+		inputUSDPer1M: 0.10,
+		cachedInputUSDPer1M: null,
+		outputUSDPer1M: null,
+	},
+};
+
+/**
+ * OpenAI Standard image token prices in USD, verified on 2026-09-11.
+ *
+ * Flare and GPT Image 2 share token rates, but may consume different token
+ * counts for the same size and quality. Estimate costs from reported usage.
+ *
+ * @see https://developers.openai.com/api/docs/pricing
+ */
+export const AI_IMAGE_MODEL_PRICING: Record<string, AIImageModelPricing> = {
+	'gpt-image-2.5-flare': {
+		textInputUSDPer1M: 5.00,
+		cachedTextInputUSDPer1M: 1.25,
+		imageInputUSDPer1M: 8.00,
+		cachedImageInputUSDPer1M: 2.00,
+		imageOutputUSDPer1M: 30.00,
+	},
+	'gpt-image-2': {
+		textInputUSDPer1M: 5.00,
+		cachedTextInputUSDPer1M: 1.25,
+		imageInputUSDPer1M: 8.00,
+		cachedImageInputUSDPer1M: 2.00,
+		imageOutputUSDPer1M: 30.00,
+	},
+};
+
+/**
+ * Hardcoded per-call pricing for hosted provider tools that do not create their
+ * own AI request row.
+ */
+export const AI_HOSTED_TOOL_PRICING_USD: Record<string, number> = {
+	web_search_call: 0.01,
+};
+
+const TOKENS_PER_PRICING_UNIT = 1_000_000;
+const COST_PRECISION = 100_000_000;
+
+/**
+ * Calculates an estimated USD cost from normalized usage and model pricing.
+ *
+ * Unknown models and incomplete paid token dimensions return null so callers do
+ * not persist misleading costs. Input-only models can omit output tokens.
+ *
+ * @param model - Provider model used by the request.
+ * @param usage - Normalized token counts from the provider response.
+ * @returns Rounded USD cost, or null when cost cannot be computed.
+ */
+export function calculateAIRequestCostUSD(
+	model: string,
+	usage: AIRequestCostUsage,
+): number | null {
+	const pricing = AI_MODEL_PRICING[canonicalModelName(model)];
+
+	if (!pricing) return null;
+	if (!validTokenCount(usage.inputTokens)) return null;
+	if (pricing.outputUSDPer1M !== null && !validTokenCount(usage.outputTokens)) return null;
+
+	const inputTokens = usage.inputTokens;
+	const outputTokens = tokenCountOrZero(usage.outputTokens);
+
+	if (inputTokens + outputTokens === 0) return null;
+
+	const cachedTokens = Math.min(tokenCountOrZero(usage.cachedTokens), inputTokens);
+	const cacheWriteTokens = Math.min(
+		tokenCountOrZero(usage.cacheWriteTokens),
+		inputTokens - cachedTokens,
+	);
+
+	if (cacheWriteTokens > 0 && pricing.cacheWriteInputMultiplier === undefined) return null;
+
+	const uncachedInputTokens = inputTokens - cachedTokens - cacheWriteTokens;
+	const longContext = pricing.longContextInputTokenThreshold !== undefined
+		&& inputTokens > pricing.longContextInputTokenThreshold;
+	const inputMultiplier = longContext ? pricing.longContextInputMultiplier ?? 1 : 1;
+	const outputMultiplier = longContext ? pricing.longContextOutputMultiplier ?? 1 : 1;
+	const inputRate = pricing.inputUSDPer1M * inputMultiplier;
+	const cachedInputRate = (pricing.cachedInputUSDPer1M ?? pricing.inputUSDPer1M) * inputMultiplier;
+	const cacheWriteInputRate = inputRate * (pricing.cacheWriteInputMultiplier ?? 1);
+	const outputRate = (pricing.outputUSDPer1M ?? 0) * outputMultiplier;
+	const cost = (
+		(uncachedInputTokens * inputRate)
+		+ (cachedTokens * cachedInputRate)
+		+ (cacheWriteTokens * cacheWriteInputRate)
+		+ (outputTokens * outputRate)
+	) / TOKENS_PER_PRICING_UNIT;
+
+	return Math.round(cost * COST_PRECISION) / COST_PRECISION;
+}
+
+/**
+ * Calculates aggregate model cost from the individual requests in an agent run.
+ *
+ * Per-request calculation is required because long-context pricing applies to
+ * an individual prompt rather than to the run's aggregate input-token total.
+ *
+ * @param model - Provider model used for each request entry.
+ * @param entries - Individual request usage entries reported by the Agents SDK.
+ * @returns Combined model cost, or null when any request cannot be priced.
+ */
+export function calculateAIRequestEntriesCostUSD(
+	model: string,
+	entries: AIRequestCostUsageEntry[],
+): number | null {
+	if (entries.length === 0) return null;
+
+	let cost = 0;
+
+	for (const entry of entries) {
+		const entryCost = calculateAIRequestCostUSD(model, entry);
+
+		if (entryCost === null) return null;
+
+		cost += entryCost;
+	}
+
+	return roundCost(cost);
+}
+
+/**
+ * Calculates an estimated image generation USD cost from provider usage.
+ *
+ * Unknown models and incomplete token modality details return null so callers
+ * do not persist misleading image costs.
+ *
+ * @param model - Provider image model used by the request.
+ * @param usage - Normalized image token counts from the provider response.
+ * @returns Rounded USD cost, or null when cost cannot be computed.
+ */
+export function calculateAIImageRequestCostUSD(
+	model: string,
+	usage: AIImageRequestCostUsage,
+): number | null {
+	const pricing = AI_IMAGE_MODEL_PRICING[canonicalModelName(model)];
+
+	if (!pricing) return null;
+	if (!validTokenCount(usage.inputTextTokens)) return null;
+	if (!validTokenCount(usage.inputImageTokens)) return null;
+	if (!validTokenCount(usage.outputImageTokens)) return null;
+
+	const cachedTextTokens = Math.min(tokenCountOrZero(usage.cachedTextTokens), usage.inputTextTokens);
+	const cachedImageTokens = Math.min(tokenCountOrZero(usage.cachedImageTokens), usage.inputImageTokens);
+	const uncachedTextTokens = usage.inputTextTokens - cachedTextTokens;
+	const uncachedImageTokens = usage.inputImageTokens - cachedImageTokens;
+	const cachedTextRate = pricing.cachedTextInputUSDPer1M ?? pricing.textInputUSDPer1M;
+	const cachedImageRate = pricing.cachedImageInputUSDPer1M ?? pricing.imageInputUSDPer1M;
+	const cost = (
+		(uncachedTextTokens * pricing.textInputUSDPer1M)
+		+ (cachedTextTokens * cachedTextRate)
+		+ (uncachedImageTokens * pricing.imageInputUSDPer1M)
+		+ (cachedImageTokens * cachedImageRate)
+		+ (usage.outputImageTokens * pricing.imageOutputUSDPer1M)
+	) / TOKENS_PER_PRICING_UNIT;
+
+	return Math.round(cost * COST_PRECISION) / COST_PRECISION;
+}
+
+/**
+ * Calculates hosted provider-tool fees from normalized billable call counts.
+ *
+ * Unknown tool names are excluded from this numeric subtotal. Use
+ * `calculateAIHostedToolCost(...)` when the caller must distinguish a complete
+ * cost from a subtotal with unpriced tools.
+ *
+ * @param usage - Billable hosted-tool call counts by normalized tool name.
+ * @returns Hosted-tool cost rounded to the request-cost precision.
+ */
+export function calculateAIHostedToolCostUSD(usage: AIHostedToolUsage): number {
+	return calculateAIHostedToolCost(usage).costUSD;
+}
+
+/**
+ * Separates priced hosted-tool fees from completed hosted tools whose provider
+ * pricing is not yet represented locally.
+ *
+ * @param usage - Billable hosted-tool call counts by normalized tool name.
+ * @returns Known tool-fee subtotal and usage that prevents a complete estimate.
+ */
+export function calculateAIHostedToolCost(usage: AIHostedToolUsage): AIHostedToolCost {
+	const unpricedUsage: AIHostedToolUsage = {};
+	let costUSD = 0;
+
+	for (const [toolName, count] of Object.entries(usage)) {
+		if (!validTokenCount(count)) continue;
+
+		const completedCalls = Math.trunc(count);
+
+		if (completedCalls === 0) continue;
+
+		const price = AI_HOSTED_TOOL_PRICING_USD[toolName];
+
+		if (price === undefined) {
+			unpricedUsage[toolName] = completedCalls;
+			continue;
+		}
+
+		costUSD += completedCalls * price;
+	}
+
+	return {
+		costUSD: roundCost(costUSD),
+		unpricedUsage,
+	};
+}
+
+/**
+ * Adds provider token cost and hosted-tool fees for one tracked request.
+ *
+ * A missing token-model price keeps the request unpriced rather than persisting
+ * a partial hosted-tool-only total.
+ *
+ * @param modelCostUSD - Token cost calculated for the model request.
+ * @param hostedToolCostUSD - Hosted provider-tool fees incurred during the request.
+ * @returns Combined request cost, or null when the model cost is unavailable.
+ */
+export function combineAIRequestCostUSD(
+	modelCostUSD: number | null,
+	hostedToolCostUSD: number,
+): number | null {
+	if (modelCostUSD === null) return null;
+
+	return roundCost(modelCostUSD + hostedToolCostUSD);
+}
+
+/**
+ * Checks whether a provider token count is present and safe to use in math.
+ *
+ * @param value - Token count candidate.
+ * @returns True when the value is a finite, non-negative number.
+ */
+function validTokenCount(value: number | null | undefined): value is number {
+	return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+
+/**
+ * Converts optional token counts into a numeric value for optional dimensions.
+ *
+ * @param value - Token count candidate.
+ * @returns Token count, or zero when the value is absent or invalid.
+ */
+function tokenCountOrZero(value: number | null | undefined): number {
+	return validTokenCount(value) ? value : 0;
+}
+
+/**
+ * Resolves provider aliases and dated snapshots onto one stable pricing key.
+ *
+ * @param model - Provider model id recorded on the request.
+ * @returns Canonical local pricing key.
+ */
+function canonicalModelName(model: string): string {
+	const undated = model.replace(/-\d{4}-\d{2}-\d{2}$/u, '');
+
+	if (undated === 'gpt-5.6') return 'gpt-5.6-sol';
+
+	return undated;
+}
+
+/**
+ * Rounds a USD cost to the precision stored in `ai_requests.cost_usd`.
+ *
+ * @param value - Cost value to round.
+ * @returns Value rounded to eight decimal places.
+ */
+function roundCost(value: number): number {
+	return Math.round(value * COST_PRECISION) / COST_PRECISION;
+}

package/src/ai/OpenAIProviderError.ts

@@ -0,0 +1,98 @@
+/**
+ * Normalized OpenAI provider failure fields used by application retry policy.
+ */
+export interface OpenAIProviderErrorDetails {
+	/** Provider error code, when supplied by the SDK or response payload. */
+	code: string | null;
+	/** HTTP status, when the provider rejected the request before streaming began. */
+	status: number | null;
+	/** Provider request identifier used for support and diagnostics. */
+	requestId: string | null;
+	/** Human-readable provider failure message. */
+	message: string;
+}
+
+const OPENAI_QUOTA_ERROR_CODES = new Set([
+	'billing_hard_limit_reached',
+	'insufficient_quota',
+]);
+
+/**
+ * Extracts stable OpenAI failure fields from SDK errors or response payloads.
+ *
+ * Streaming Responses failures can carry no HTTP status while still exposing a
+ * provider `code`, so callers must not classify them from status alone.
+ *
+ * @param value - Unknown SDK error or provider response payload.
+ * @returns Normalized provider failure details.
+ */
+export function openAIProviderError(value: unknown): OpenAIProviderErrorDetails {
+	const record = objectRecord(value);
+	const nestedError = objectRecord(record?.error);
+	const code = stringField(record?.code)
+		?? stringField(nestedError?.code);
+	const status = numberField(record?.status);
+	const requestId = stringField(record?.requestID)
+		?? stringField(record?.requestId)
+		?? stringField(nestedError?.request_id);
+	const message = value instanceof Error
+		? value.message
+		: stringField(record?.message)
+			?? stringField(nestedError?.message)
+			?? 'OpenAI request failed.';
+
+	return {
+		code,
+		status,
+		requestId,
+		message,
+	};
+}
+
+/**
+ * Checks whether an OpenAI failure represents exhausted account or project quota.
+ *
+ * @param value - Unknown SDK error or provider response payload.
+ * @returns True when the provider error code requires credits or billing changes.
+ */
+export function isOpenAIQuotaError(value: unknown): boolean {
+	const code = openAIProviderError(value).code;
+
+	return code !== null && OPENAI_QUOTA_ERROR_CODES.has(code);
+}
+
+/**
+ * Narrows an unknown value to a non-array object record.
+ *
+ * @param value - Unknown value to inspect.
+ * @returns Object record, or null for unsupported values.
+ */
+function objectRecord(value: unknown): Record<string, unknown> | null {
+	return value !== null && typeof value === 'object' && !Array.isArray(value)
+		? value as Record<string, unknown>
+		: null;
+}
+
+/**
+ * Returns a non-empty string field.
+ *
+ * @param value - Unknown field value.
+ * @returns Trimmed string, or null.
+ */
+function stringField(value: unknown): string | null {
+	return typeof value === 'string' && value.trim()
+		? value.trim()
+		: null;
+}
+
+/**
+ * Returns a finite numeric field.
+ *
+ * @param value - Unknown field value.
+ * @returns Finite number, or null.
+ */
+function numberField(value: unknown): number | null {
+	return typeof value === 'number' && Number.isFinite(value)
+		? value
+		: null;
+}

package/src/ai/OpenAIQuotaRetry.ts

@@ -0,0 +1,183 @@
+import type { OpenAIQuotaRetryMetadata, OpenAIQuotaRetryDecision } from './contracts/QuotaRetry';
+export type { OpenAIQuotaRetryMetadata, OpenAIQuotaRetryDecision } from './contracts/QuotaRetry';
+import type { AiRequest } from './AiRequest.js';
+import { isOpenAIQuotaError, openAIProviderError } from './OpenAIProviderError';
+
+const OPENAI_QUOTA_RETRY_METADATA_KEY = 'openAIQuotaRetry';
+
+/**
+ * Builds a bounded exponential retry decision for an OpenAI quota failure.
+ *
+ * @param error - Unknown provider error thrown by the Agents SDK.
+ * @param request - Persisted AI request carrying previous quota retry metadata.
+ * @param now - Current time used for deterministic scheduling.
+ * @returns Quota retry decision, or null for another failure category.
+ */
+export function openAIQuotaRetryDecision(
+	error: unknown,
+	request: AiRequest,
+	now = new Date(),
+): OpenAIQuotaRetryDecision | null {
+	if (!isOpenAIQuotaError(error)) return null;
+
+	const providerError = openAIProviderError(error);
+	const previous = quotaRetryMetadata(request.metadata);
+	const deferralCount = (previous?.deferralCount ?? 0) + 1;
+	const firstDeferredAt = validDate(previous?.firstDeferredAt)
+		?? request.startedAt
+		?? request.createdAt
+		?? now;
+	const retryUntil = validDate(previous?.retryUntil)
+		?? new Date(firstDeferredAt.getTime() + (quotaRetryWindowSeconds() * 1000));
+	const expired = now.getTime() >= retryUntil.getTime();
+	const delaySeconds = expired
+		? 0
+		: Math.min(
+			quotaRetryMaxSeconds(),
+			quotaRetryInitialSeconds() * (2 ** Math.max(0, deferralCount - 1)),
+		);
+	const retryAt = new Date(Math.min(
+		retryUntil.getTime(),
+		now.getTime() + (delaySeconds * 1000),
+	));
+	const code = providerError.code ?? 'insufficient_quota';
+
+	return {
+		code,
+		message: providerError.message,
+		deferralCount,
+		delaySeconds,
+		retryAt,
+		retryUntil,
+		expired,
+		metadata: {
+			code,
+			deferralCount,
+			firstDeferredAt: firstDeferredAt.toISOString(),
+			lastDeferredAt: now.toISOString(),
+			retryAt: retryAt.toISOString(),
+			retryUntil: retryUntil.toISOString(),
+		},
+	};
+}
+
+/**
+ * Merges quota retry state into existing AI request metadata.
+ *
+ * @param metadata - Existing request metadata.
+ * @param quotaRetry - Quota retry state to persist.
+ * @returns Request metadata containing the latest retry schedule.
+ */
+export function withOpenAIQuotaRetryMetadata(
+	metadata: Record<string, unknown> | null,
+	quotaRetry: OpenAIQuotaRetryMetadata,
+): Record<string, unknown> {
+	return {
+		...(metadata ?? {}),
+		[OPENAI_QUOTA_RETRY_METADATA_KEY]: quotaRetry,
+	};
+}
+
+/**
+ * Removes completed quota retry state from AI request metadata.
+ *
+ * @param metadata - Existing request metadata.
+ * @returns Metadata without the internal quota retry entry.
+ */
+export function withoutOpenAIQuotaRetryMetadata(
+	metadata: Record<string, unknown> | null,
+): Record<string, unknown> {
+	const next = {
+		...(metadata ?? {}),
+	};
+
+	delete next[OPENAI_QUOTA_RETRY_METADATA_KEY];
+
+	return next;
+}
+
+/**
+ * Reads validated quota retry metadata from an AI request metadata object.
+ *
+ * @param metadata - Existing request metadata.
+ * @returns Persisted quota retry state, or null.
+ */
+function quotaRetryMetadata(
+	metadata: Record<string, unknown> | null,
+): OpenAIQuotaRetryMetadata | null {
+	const value = metadata?.[OPENAI_QUOTA_RETRY_METADATA_KEY];
+
+	if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+
+	const record = value as Record<string, unknown>;
+
+	if (
+		typeof record.code !== 'string'
+		|| typeof record.deferralCount !== 'number'
+		|| typeof record.firstDeferredAt !== 'string'
+		|| typeof record.lastDeferredAt !== 'string'
+		|| typeof record.retryAt !== 'string'
+		|| typeof record.retryUntil !== 'string'
+	) {
+		return null;
+	}
+
+	return record as OpenAIQuotaRetryMetadata;
+}
+
+/**
+ * Parses one valid date-like value.
+ *
+ * @param value - Unknown persisted date value.
+ * @returns Valid date, or null.
+ */
+function validDate(value: unknown): Date | null {
+	if (value instanceof Date && !Number.isNaN(value.getTime())) return value;
+	if (typeof value !== 'string' || !value.trim()) return null;
+
+	const date = new Date(value);
+
+	return Number.isNaN(date.getTime()) ? null : date;
+}
+
+/**
+ * Returns the first quota retry delay in seconds.
+ *
+ * @returns Positive retry delay.
+ */
+function quotaRetryInitialSeconds(): number {
+	return positiveEnvironmentNumber('OPENAI_QUOTA_RETRY_INITIAL_SECONDS', 900);
+}
+
+/**
+ * Returns the maximum quota retry delay in seconds.
+ *
+ * @returns Positive maximum retry delay.
+ */
+function quotaRetryMaxSeconds(): number {
+	return positiveEnvironmentNumber('OPENAI_QUOTA_RETRY_MAX_SECONDS', 3600);
+}
+
+/**
+ * Returns the total quota retry window in seconds.
+ *
+ * @returns Positive retry window.
+ */
+function quotaRetryWindowSeconds(): number {
+	return positiveEnvironmentNumber('OPENAI_QUOTA_RETRY_WINDOW_SECONDS', 86400);
+}
+
+/**
+ * Reads a positive finite environment number.
+ *
+ * @param name - Environment variable name.
+ * @param fallback - Value used when configuration is absent or invalid.
+ * @returns Positive finite number.
+ */
+function positiveEnvironmentNumber(name: string, fallback: number): number {
+	const value = Number(process.env[name]);
+
+	return Number.isFinite(value) && value > 0
+		? value
+		: fallback;
+}