@db3.ai/app 0.1.0-beta.1

package/dist/ai/Ai.js

@@ -0,0 +1,1771 @@
+/// <reference path="./sdkNodeCompatibility.d.ts" preserve="true" />
+import OpenAI from 'openai';
+import { OpenAIProvider } from '@openai/agents';
+import { aiExecutionContext, scopedAiOptions } from './AiExecutionContext.js';
+import { zodTextFormat } from 'openai/helpers/zod';
+import { parseJsonObjectText, responseErrorMessage, responseOutputText } from '@db3.ai/pure';
+import { app } from '../server/appContext.js';
+import { AiConversation } from './AiConversation.js';
+import { AiMessage, AI_MESSAGE_ROLE } from './AiMessage.js';
+import { AiRequest, AI_REQUEST_STATUS } from './AiRequest.js';
+const defaultAIConfig = { model: 'gpt-4.1-mini' };
+import { estimateTokensFromText } from './Estimates.js';
+import { calculateAIImageRequestCostUSD, calculateAIRequestCostUSD } from './Models.js';
+import { AI_PROVIDER } from './contracts/AI.js';
+import { AIAllowanceExceededError, AIConfigurationError, AIRequestError } from './AIErrors.js';
+import { isFailoverableFailure, isFailoverableResponse } from './AIFailover.js';
+import { providerChainFromEnvironment, resolveProviderChain, simulatedProviderOutage } from './AIProviders.js';
+import { AIRateLimitDeferredError, AIRateLimiter, embeddingsRateLimitEndpoint, imagesRateLimitEndpoint, providerResponseMetadata, responsesRateLimitEndpoint } from './AIRateLimiter.js';
+import { isOpenAIQuotaError, openAIProviderError } from './OpenAIProviderError.js';
+import { providerReportedCostUSD } from './ProviderCosts.js';
+import { sendResponsesRequest } from './ResponsesProviderCall.js';
+/**
+ * Raised when exact provider usage could not be made durable after bounded retries.
+ *
+ * This is deliberately distinct from provider and transport failures so callers
+ * must not issue another paid provider request in response to a database error.
+ */
+export class AIUsagePersistenceError extends Error {
+    aiRequestId;
+    persistenceCause;
+    /** Indicates that provider execution already occurred and must not be replayed. */
+    providerExecuted = true;
+    /**
+     * Creates a terminal AI usage persistence failure.
+     *
+     * @param aiRequestId - Stable tracked request whose assigned outcome was not saved.
+     * @param persistenceCause - Last database error returned by the bounded save attempts.
+     */
+    constructor(aiRequestId, persistenceCause) {
+        super(`Unable to persist terminal AI usage for request ${aiRequestId ?? 'unknown'}.`);
+        this.aiRequestId = aiRequestId;
+        this.persistenceCause = persistenceCause;
+        this.name = 'AIUsagePersistenceError';
+    }
+}
+/** Total terminal persistence attempts, including the initial save. */
+const TERMINAL_AI_REQUEST_SAVE_ATTEMPTS = 3;
+/**
+ * Small application-level wrapper around OpenAI's Responses API.
+ *
+ * The service supports plain text generation, structured Zod-backed generation,
+ * and persistence of conversations, messages, provider payloads, token usage,
+ * and estimated request cost.
+ */
+export class Ai {
+    options;
+    modelConfig;
+    /** Configured model constructors for app-owned schema extensions. */
+    models;
+    /** Logical ownership field used by this application. */
+    scopeField;
+    rateLimiter;
+    /**
+     * Create an AI service instance.
+     *
+     * Pass options to override environment configuration or to inject a test
+     * fetch implementation.
+     */
+    constructor(options = {}, modelConfig = defaultAIConfig) {
+        this.options = options;
+        this.modelConfig = modelConfig;
+        if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0))
+            throw new AIConfigurationError('timeoutMs must be positive.');
+        this.models = { conversation: AiConversation, request: AiRequest, message: AiMessage, ...options.models };
+        this.scopeField = options.scopeField ?? 'scope';
+        this.rateLimiter = options.rateLimiter === false
+            ? null
+            : options.rateLimiter ?? new AIRateLimiter();
+    }
+    /**
+     * Returns a named model from application config.
+     *
+     * Concrete agents use their class name as the key and keep a colocated
+     * fallback for configurations that omit the named override.
+     *
+     * @param name - Stable model configuration name.
+     * @param fallback - Model to use when the named entry is absent or empty.
+     * @returns Configured named model or the supplied fallback.
+     *
+     * @example
+     * protected readonly model = app().ai.config(
+     * 	'ArticleGenerationAgent',
+     * 	'gpt-5.6-sol',
+     * );
+     */
+    config(name, fallback) {
+        return this.modelConfig[name]?.trim() || fallback;
+    }
+    /**
+     * Default model used when a call does not provide its own model.
+     *
+     * @returns Injected model override or the application config default.
+     */
+    get model() {
+        return this.options.model || this.modelConfig.model;
+    }
+    /**
+     * Whether the service has an API key available.
+     */
+    isConfigured() {
+        return Boolean(this.apiKey());
+    }
+    /**
+     * Checks application/customer allowance before a provider call starts.
+     *
+     * The default implementation is a no-op. Apps can inject an allowance hook
+     * through AIOptions to enforce user, team, website, or billing-period limits
+     * without leaking billing concerns into prompt code.
+     *
+     * @param input - Request context used by the allowance policy.
+     */
+    async checkAllowance(input) {
+        if (!this.options.allowance)
+            return;
+        await this.options.allowance(input);
+    }
+    /**
+     * Resolves a provider selection into an ordered failover attempt chain.
+     *
+     * Precedence: the explicit selection, then the app-level default from
+     * AIOptions.provider or AI_PROVIDER_CHAIN, then OpenAI alone. The OpenAI
+     * entry uses this service's resolved key, base URL, and model so single
+     * provider behavior is unchanged.
+     *
+     * @param selection - Selection from a call or agent, or null for defaults.
+     * @param model - Model for the OpenAI entry, or null for the app default.
+     * @returns Ordered configured attempts.
+     * @throws AIConfigurationError when no provider in the chain is usable.
+     */
+    resolveProviders(selection = null, model = null) {
+        return resolveProviderChain({
+            selection: selection ?? this.options.provider ?? providerChainFromEnvironment(),
+            openai: {
+                apiKey: this.apiKey(),
+                baseUrl: this.baseUrl(),
+                model: model || this.model,
+            },
+        });
+    }
+    /**
+     * Generate text and return only the assistant's text.
+     *
+     * Requests are tracked by default. Pass `saveAiResponse: false` in options
+     * for one-off calls that should not create conversation, request, or message
+     * rows. Use {@link generateTextWithResponse} when callers need persisted ids.
+     *
+     * @throws AIConfigurationError when no API key is configured.
+     * @throws AIRequestError when the provider rejects the request or returns no text.
+     */
+    async generateText(input, options = {}) {
+        const result = await this.generateTextResult(input, options);
+        return result.text;
+    }
+    /**
+     * Generate text and return the assistant text plus tracking ids.
+     *
+     * Creates or appends to an AI conversation, stores system/user messages before
+     * sending the provider request, then stores the assistant message, raw response,
+     * usage metrics, and estimated cost after completion unless
+     * `saveAiResponse: false` is provided.
+     *
+     * @throws AIConfigurationError when no API key is configured.
+     * @throws AIRequestError when the provider rejects the request or returns no text.
+     */
+    async generateTextWithResponse(input, options = {}) {
+        return this.generateTextResult(input, options);
+    }
+    /**
+     * Generate structured JSON that must satisfy the supplied Zod schema.
+     *
+     * The schema is sent to the Responses API as a text format, the raw provider
+     * response is logged, and the returned text is parsed and validated locally
+     * before the typed value is returned.
+     *
+     * @throws AIConfigurationError when no API key is configured.
+     * @throws AIRequestError when the provider rejects the request or returns no text.
+     * @throws z.ZodError when the provider output does not match the schema.
+     */
+    async generateStructured(input, options = {}) {
+        const result = await this.generateTextResult({
+            model: input.model,
+            provider: input.provider,
+            instructions: input.instructions,
+            input: input.input,
+            maxOutputTokens: input.maxOutputTokens,
+        }, {
+            ...options,
+            agent: options.agent ?? input.schemaName,
+            metadata: {
+                ...(options.metadata ?? {}),
+                schemaName: input.schemaName,
+            },
+            saveAiResponse: options.saveAiResponse,
+            operation: 'responses.create.structured',
+        }, {
+            text: {
+                format: zodTextFormat(input.schema, input.schemaName),
+            },
+        });
+        return {
+            data: input.schema.parse(parseJsonObjectText(result.text)),
+            aiRequestId: result.aiRequestId,
+            aiResponseId: result.aiResponseId,
+            conversationId: result.conversationId,
+        };
+    }
+    /**
+     * Send a Responses API request through the resolved provider chain and
+     * optionally track it in application tables.
+     *
+     * Tracking is intentionally started before the provider call so failed or slow
+     * requests still leave an auditable pending/failed row with the prompt that was
+     * sent. One stable logical AiRequest is retargeted to the provider that settles
+     * the call. Provider-executed intermediate failures are appended as child rows
+     * with their own usage/cost and summarized in `metadata.providerAttempts`.
+     *
+     * Failover moves to the next provider only for failoverable failures such as
+     * rate limits, overload, 5xx, network errors, and exhausted quota. The final
+     * attempt keeps the existing single-provider error contract, including queue
+     * rate-limit deferrals.
+     */
+    async generateTextResult(input, options = {}, extraRequest = {}) {
+        options = scopedAiOptions(options, this.scopeField);
+        assertIndependentUsage(options);
+        if (typeof input?.input !== 'string' || !input.input.trim())
+            throw new AIRequestError('Text input is required.', 'invalid_input');
+        if (typeof input.instructions !== 'string')
+            throw new AIRequestError('Instructions must be a string.', 'invalid_input');
+        if (input.maxOutputTokens !== undefined && (!Number.isSafeInteger(input.maxOutputTokens) || input.maxOutputTokens < 1))
+            throw new AIRequestError('maxOutputTokens must be a positive integer.', 'invalid_input');
+        const operation = options.operation ?? 'responses.create';
+        const attempts = this.resolveProviders(input.provider ?? null, input.model ?? null)
+            .filter(attempt => attempt.supportsResponsesApi);
+        const attemptFailures = [];
+        let tracked = null;
+        let trackedSettled = false;
+        if (attempts.length === 0) {
+            throw new AIConfigurationError('No configured AI provider in the chain supports the Responses API.');
+        }
+        for (let index = 0; index < attempts.length; index++) {
+            const attempt = attempts[index];
+            const hasFallback = index < attempts.length - 1;
+            const attemptStartMs = Date.now();
+            const request = {
+                model: attempt.model,
+                instructions: input.instructions,
+                input: input.input,
+                store: false,
+                ...(attempt.provider === AI_PROVIDER.openai ? { service_tier: 'default' } : {}),
+                ...maxOutputTokensPayload(input.maxOutputTokens),
+                ...extraRequest,
+            };
+            const estimatedTokens = estimatedResponseTokens(input, request);
+            let lease = null;
+            let providerStarted = false;
+            try {
+                lease = await this.acquireRateLimit({
+                    provider: attempt.provider,
+                    endpoint: responsesRateLimitEndpoint(),
+                    model: attempt.model,
+                    operation,
+                    estimatedTokens,
+                    aiRequest: tracked?.aiRequest ?? null,
+                });
+                if (!tracked && options.saveAiResponse !== false) {
+                    tracked = await this.startTrackedRequest(request, input, {
+                        ...options,
+                        operation,
+                    }, attempt);
+                }
+                else if (tracked) {
+                    await this.retargetTrackedRequest(tracked, attempt, request);
+                }
+                await this.checkAllowance({
+                    provider: attempt.provider,
+                    endpoint: responsesRateLimitEndpoint(),
+                    model: attempt.model,
+                    operation,
+                    user: tracked?.userId ?? options.user ?? this.activeUser(),
+                    scope: tracked?.scopeId ?? options[this.scopeField] ?? null,
+                    aiRequest: tracked?.aiRequest ?? null,
+                    estimatedTokens,
+                    usage: options.usage ?? null,
+                    metadata: options.metadata ?? null,
+                });
+                await this.attachRateLimitRequest(lease, tracked?.aiRequest ?? null);
+                const simulatedOutage = simulatedProviderOutage(attempt.provider);
+                if (simulatedOutage)
+                    throw simulatedOutage;
+                providerStarted = true;
+                const result = await sendResponsesRequest({
+                    baseUrl: attempt.baseUrl,
+                    apiKey: attempt.apiKey,
+                    request,
+                    fetcher: this.fetcher(),
+                });
+                const { payload, metadata } = result;
+                if (!result.ok) {
+                    const message = responseErrorMessage(payload) || `AI provider ${attempt.provider} request failed with HTTP ${result.status}.`;
+                    if (hasFallback && isFailoverableResponse(result.status, payload)) {
+                        const failure = providerAttemptFailure(attempt, attemptStartMs, message, result.status, responseErrorCode(payload));
+                        attemptFailures.push(failure);
+                        if (tracked) {
+                            await this.appendTrackedProviderAttempt(tracked, {
+                                attempt,
+                                request,
+                                response: payload,
+                                failure,
+                                metadata,
+                                lease,
+                                startedAtMs: attemptStartMs,
+                            });
+                        }
+                        await this.observeRateLimit(lease, metadata);
+                        lease = null;
+                        continue;
+                    }
+                    const deferred = isRateLimitFailure(result.status, payload)
+                        ? rateLimitDeferredError(lease, metadata, message)
+                        : null;
+                    if (tracked) {
+                        attachProviderAttempts(tracked.aiRequest, attemptFailures);
+                        await this.failTrackedRequest(tracked, payload, message, metadata, lease);
+                        trackedSettled = true;
+                    }
+                    await this.observeRateLimit(lease, metadata);
+                    lease = null;
+                    if (deferred)
+                        throw deferred;
+                    throw new AIRequestError(message, responseErrorCode(payload));
+                }
+                const text = payload?.status !== undefined && payload.status !== 'completed' ? null : responseOutputText(payload);
+                if (!text) {
+                    const message = `AI provider ${attempt.provider} did not return a valid response.`;
+                    if (tracked) {
+                        attachProviderAttempts(tracked.aiRequest, attemptFailures);
+                        await this.failTrackedRequest(tracked, payload, message, metadata, lease);
+                        trackedSettled = true;
+                    }
+                    await this.observeRateLimit(lease, metadata);
+                    lease = null;
+                    throw new AIRequestError(message);
+                }
+                if (tracked) {
+                    attachProviderAttempts(tracked.aiRequest, attemptFailures);
+                    await this.completeTrackedRequest(tracked, payload, metadata, lease);
+                    trackedSettled = true;
+                    await this.saveMessage({
+                        conversation: tracked.conversation,
+                        aiRequest: tracked.aiRequest,
+                        user: tracked.userId,
+                        scope: tracked.scopeId,
+                        role: AI_MESSAGE_ROLE.assistant,
+                        content: text,
+                        provider: tracked.provider,
+                        model: tracked.model,
+                        sequence: tracked.nextSequence,
+                        metadata: tracked.aiRequest.metadata,
+                    });
+                }
+                await this.observeRateLimit(lease, metadata);
+                lease = null;
+                return {
+                    text,
+                    aiRequestId: tracked?.aiRequest.id ? String(tracked.aiRequest.id) : null,
+                    aiResponseId: tracked?.aiRequest.id ? String(tracked.aiRequest.id) : null,
+                    conversationId: tracked?.conversation.id ? String(tracked.conversation.id) : null,
+                };
+            }
+            catch (error) {
+                const failedLease = lease;
+                if (error instanceof AIUsagePersistenceError) {
+                    try {
+                        await this.releaseRateLimit(lease);
+                    }
+                    finally {
+                        throw error;
+                    }
+                }
+                await this.releaseRateLimit(lease);
+                lease = null;
+                if (hasFallback && !trackedSettled && isFailoverableFailure(error)) {
+                    const failure = providerAttemptFailureFromError(attempt, attemptStartMs, error);
+                    attemptFailures.push(failure);
+                    if (tracked && providerStarted) {
+                        await this.appendTrackedProviderAttempt(tracked, {
+                            attempt,
+                            request,
+                            response: null,
+                            failure,
+                            metadata: emptyProviderResponseMetadata(),
+                            lease: failedLease,
+                            startedAtMs: attemptStartMs,
+                        });
+                    }
+                    continue;
+                }
+                if (tracked && !trackedSettled && !(error instanceof AIRequestError) && !(error instanceof AIRateLimitDeferredError)) {
+                    attachProviderAttempts(tracked.aiRequest, attemptFailures);
+                    await this.failTrackedRequest(tracked, null, errorMessage(error), emptyProviderResponseMetadata(), failedLease, providerStarted);
+                }
+                throw error;
+            }
+        }
+        // Unreachable: the final attempt always returns or throws above.
+        throw new AIRequestError();
+    }
+    /**
+     * Points an existing tracked request at the provider attempt now being tried.
+     *
+     * @param tracked - Tracked request created by an earlier attempt.
+     * @param attempt - Provider attempt about to run.
+     * @param request - Provider request payload for this attempt.
+     */
+    async retargetTrackedRequest(tracked, attempt, request) {
+        if (tracked.provider === attempt.provider && tracked.model === attempt.model)
+            return;
+        tracked.provider = attempt.provider;
+        tracked.model = attempt.model;
+        tracked.aiRequest.assign({
+            provider: attempt.provider,
+            model: attempt.model,
+            request,
+        });
+        await tracked.aiRequest.save();
+    }
+    /**
+     * Appends one failed provider execution beneath the stable logical request.
+     *
+     * Failover retargets the logical request to the provider that ultimately
+     * settles it. Keeping prior provider executions as children prevents their
+     * returned usage and cost from being overwritten while preserving the public
+     * logical request id used by callers and application records.
+     *
+     * @param tracked - Stable logical request that owns the failover chain.
+     * @param input - Failed provider execution payload, usage, and audit metadata.
+     */
+    async appendTrackedProviderAttempt(tracked, input) {
+        const usage = tokenUsage(input.response);
+        const modelCostUSD = textRequestCostUSD(input.attempt.provider, input.attempt.model, usage, input.response);
+        const aiRequest = new this.models.request({
+            conversation: tracked.conversation,
+            parentAiRequest: tracked.aiRequest,
+            user: tracked.userId,
+            [this.scopeField]: tracked.scopeId,
+            provider: input.attempt.provider,
+            model: input.attempt.model,
+            operation: `${tracked.aiRequest.operation || 'responses.create'}.attempt`,
+            status: AI_REQUEST_STATUS.failed,
+            request: input.request,
+            response: input.response,
+            providerRequestId: input.metadata.providerRequestId,
+            providerProcessingMs: input.metadata.providerProcessingMs,
+            rateLimitBucket: input.lease?.bucket ?? null,
+            rateLimitSnapshot: input.metadata.rateLimitSnapshot,
+            startedAt: new Date(input.startedAtMs),
+            completedAt: new Date(),
+            durationMs: input.failure.durationMs,
+            inputTokens: usage.inputTokens,
+            outputTokens: usage.outputTokens,
+            totalTokens: usage.totalTokens,
+            reasoningTokens: usage.reasoningTokens,
+            cachedTokens: usage.cachedTokens,
+            cacheWriteTokens: usage.cacheWriteTokens,
+            costUSD: modelCostUSD,
+            knownCostUSD: modelCostUSD ?? 0,
+            errorCode: input.failure.code,
+            errorMessage: input.failure.message,
+            metadata: {
+                ...(tracked.aiRequest.metadata ?? {}),
+                outcome: 'provider_failover_attempt',
+                providerAttempt: input.failure,
+                providerStarted: true,
+            },
+        });
+        await saveTerminalAiRequest(aiRequest);
+    }
+    /**
+     * Create the conversation, pending request row, and initial system/user
+     * messages for a tracked provider call.
+     */
+    async startTrackedRequest(request, input, options, attempt) {
+        const user = options.user ?? this.activeUser();
+        const userId = userRecordId(user);
+        const scopeId = scopeRecordId(options[this.scopeField] ?? null);
+        const conversation = await this.resolveConversation({
+            conversation: options.conversation,
+            userId,
+            scopeId,
+            agent: options.agent ?? null,
+            title: options.title ?? null,
+            metadata: options.metadata ?? null,
+        });
+        const startedAt = new Date();
+        const startTimeMs = Date.now();
+        const aiRequest = await new this.models.request({
+            conversation,
+            parentAiRequest: options.parentAiRequest ?? null,
+            user: userId,
+            [this.scopeField]: scopeId,
+            provider: attempt.provider,
+            model: attempt.model,
+            operation: options.operation,
+            status: AI_REQUEST_STATUS.pending,
+            request,
+            metadata: options.metadata ?? null,
+            startedAt,
+        }).save();
+        let nextSequence = await this.nextMessageSequence(conversation);
+        nextSequence = await this.saveMessage({
+            conversation,
+            aiRequest,
+            user: userId,
+            scope: scopeId,
+            role: AI_MESSAGE_ROLE.system,
+            content: input.instructions,
+            provider: attempt.provider,
+            model: attempt.model,
+            sequence: nextSequence,
+            metadata: options.metadata ?? null,
+        });
+        nextSequence = await this.saveMessage({
+            conversation,
+            aiRequest,
+            user: userId,
+            scope: scopeId,
+            role: AI_MESSAGE_ROLE.user,
+            content: input.input,
+            provider: attempt.provider,
+            model: attempt.model,
+            sequence: nextSequence,
+            metadata: options.metadata ?? null,
+        });
+        return {
+            aiRequest,
+            conversation,
+            nextSequence,
+            startTimeMs,
+            userId,
+            scopeId,
+            model: attempt.model,
+            provider: attempt.provider,
+        };
+    }
+    /**
+     * Marks a tracked text request completed with exact provider usage and cost.
+     *
+     * Assistant-message persistence happens only after this terminal request update
+     * succeeds, allowing the caller to protect completed usage from ancillary errors.
+     *
+     * @param tracked - Tracked logical request state.
+     * @param response - Provider response payload containing terminal usage.
+     * @param metadata - Parsed provider response metadata.
+     * @param lease - Rate-limit lease used for the provider request.
+     */
+    async completeTrackedRequest(tracked, response, metadata = emptyProviderResponseMetadata(), lease = null) {
+        const usage = tokenUsage(response);
+        const costUSD = textRequestCostUSD(tracked.provider, tracked.model, usage, response);
+        tracked.aiRequest.assign({
+            response,
+            providerRequestId: metadata.providerRequestId,
+            providerProcessingMs: metadata.providerProcessingMs,
+            rateLimitBucket: lease?.bucket ?? null,
+            rateLimitSnapshot: metadata.rateLimitSnapshot,
+            status: AI_REQUEST_STATUS.completed,
+            completedAt: new Date(),
+            durationMs: Date.now() - tracked.startTimeMs,
+            inputTokens: usage.inputTokens,
+            outputTokens: usage.outputTokens,
+            totalTokens: usage.totalTokens,
+            reasoningTokens: usage.reasoningTokens,
+            cachedTokens: usage.cachedTokens,
+            cacheWriteTokens: usage.cacheWriteTokens,
+            costUSD,
+            knownCostUSD: costUSD ?? 0,
+        });
+        await saveTerminalAiRequest(tracked.aiRequest);
+    }
+    /**
+     * Mark a tracked request failed with the provider error code, when available.
+     *
+     * @param tracked - Tracked logical request state.
+     * @param response - Provider response payload, when available.
+     * @param message - Failure message to persist.
+     * @param metadata - Parsed provider response metadata.
+     * @param lease - Rate-limit lease used for the provider request.
+     * @param providerStarted - Whether execution crossed the external provider boundary.
+     */
+    async failTrackedRequest(tracked, response, message, metadata = emptyProviderResponseMetadata(), lease = null, providerStarted = true) {
+        const usage = tokenUsage(response);
+        const costUSD = !providerStarted
+            ? 0
+            : textRequestCostUSD(tracked.provider, tracked.model, usage, response);
+        tracked.aiRequest.assign({
+            response,
+            providerRequestId: metadata.providerRequestId,
+            providerProcessingMs: metadata.providerProcessingMs,
+            rateLimitBucket: lease?.bucket ?? null,
+            rateLimitSnapshot: metadata.rateLimitSnapshot,
+            status: AI_REQUEST_STATUS.failed,
+            completedAt: new Date(),
+            durationMs: Date.now() - tracked.startTimeMs,
+            inputTokens: usage.inputTokens,
+            outputTokens: usage.outputTokens,
+            totalTokens: usage.totalTokens,
+            reasoningTokens: usage.reasoningTokens,
+            cachedTokens: usage.cachedTokens,
+            cacheWriteTokens: usage.cacheWriteTokens,
+            costUSD,
+            knownCostUSD: costUSD ?? 0,
+            errorCode: responseErrorCode(response),
+            errorMessage: message,
+            metadata: {
+                ...(tracked.aiRequest.metadata ?? {}),
+                providerStarted,
+            },
+        });
+        await saveTerminalAiRequest(tracked.aiRequest);
+    }
+    /**
+     * Resolve the target conversation for a tracked request.
+     *
+     * Existing conversations can be supplied by record or id; otherwise a new
+     * conversation is created using the provided context.
+     */
+    async resolveConversation(input) {
+        if (input.conversation instanceof AiConversation) {
+            return input.conversation;
+        }
+        if (typeof input.conversation === 'string' && input.conversation.trim()) {
+            return await this.models.conversation.findOrFail(input.conversation);
+        }
+        return await new this.models.conversation({
+            user: input.userId,
+            [this.scopeField]: input.scopeId,
+            agent: input.agent,
+            title: input.title,
+            metadata: input.metadata,
+        }).save();
+    }
+    /**
+     * Resolves an optional conversation without creating a new one.
+     *
+     * @param conversation - Optional conversation record or id.
+     * @returns Existing conversation record, or null when omitted.
+     */
+    async resolveOptionalConversation(conversation) {
+        if (conversation instanceof AiConversation)
+            return conversation;
+        if (typeof conversation === 'string' && conversation.trim()) {
+            return await this.models.conversation.findOrFail(conversation);
+        }
+        return null;
+    }
+    /**
+     * Return the next message sequence number for a saved conversation.
+     */
+    async nextMessageSequence(conversation) {
+        if (!conversation.id) {
+            throw new Error('AI conversation must be saved before adding messages.');
+        }
+        const lastMessage = await this.models.message
+            .where('conversation', String(conversation.id))
+            .orderBy('sequence', 'desc')
+            .first();
+        return (lastMessage?.sequence ?? 0) + 1;
+    }
+    /**
+     * Persist one conversation message and return the following sequence number.
+     */
+    async saveMessage(input) {
+        await new this.models.message({
+            conversation: input.conversation,
+            aiRequest: input.aiRequest,
+            user: input.user,
+            [this.scopeField]: input.scope,
+            role: input.role,
+            sequence: input.sequence,
+            content: input.content,
+            contentJson: input.contentJson ?? null,
+            provider: input.provider,
+            model: input.model,
+            metadata: input.metadata,
+        }).save();
+        return input.sequence + 1;
+    }
+    /**
+     * Create a pending request row for an embedding call.
+     */
+    async startTrackedEmbeddingRequest(request, options, model) {
+        const user = options.user ?? this.activeUser();
+        const userId = userRecordId(user);
+        const scopeId = scopeRecordId(options[this.scopeField] ?? null);
+        const conversation = await this.resolveOptionalConversation(options.conversation);
+        const startTimeMs = Date.now();
+        const aiRequest = await new this.models.request({
+            conversation,
+            parentAiRequest: options.parentAiRequest ?? null,
+            user: userId,
+            [this.scopeField]: scopeId,
+            provider: AI_PROVIDER.openai,
+            model,
+            operation: options.operation,
+            status: AI_REQUEST_STATUS.pending,
+            request,
+            metadata: options.metadata ?? null,
+            startedAt: new Date(),
+        }).save();
+        return {
+            aiRequest,
+            startTimeMs,
+            model,
+        };
+    }
+    /**
+     * Mark an embedding request completed with normalized token usage.
+     */
+    async completeTrackedEmbeddingRequest(tracked, response, metadata = emptyProviderResponseMetadata(), lease = null) {
+        const usage = embeddingTokenUsage(response);
+        const costUSD = calculateAIRequestCostUSD(tracked.model, usage);
+        tracked.aiRequest.assign({
+            response: compactEmbeddingResponse(response),
+            providerRequestId: metadata.providerRequestId,
+            providerProcessingMs: metadata.providerProcessingMs,
+            rateLimitBucket: lease?.bucket ?? null,
+            rateLimitSnapshot: metadata.rateLimitSnapshot,
+            status: AI_REQUEST_STATUS.completed,
+            completedAt: new Date(),
+            durationMs: Date.now() - tracked.startTimeMs,
+            inputTokens: usage.inputTokens,
+            outputTokens: usage.outputTokens,
+            totalTokens: usage.totalTokens,
+            reasoningTokens: usage.reasoningTokens,
+            cachedTokens: usage.cachedTokens,
+            cacheWriteTokens: usage.cacheWriteTokens,
+            costUSD,
+            knownCostUSD: costUSD ?? 0,
+        });
+        await saveTerminalAiRequest(tracked.aiRequest);
+    }
+    /**
+     * Mark an embedding request failed and keep a compact provider payload.
+     *
+     * @param tracked - Tracked embedding request state.
+     * @param response - Provider response payload, when available.
+     * @param message - Failure message to persist.
+     * @param metadata - Parsed provider response metadata.
+     * @param lease - Rate-limit lease used for the provider request.
+     * @param providerStarted - Whether execution crossed the external provider boundary.
+     */
+    async failTrackedEmbeddingRequest(tracked, response, message, metadata = emptyProviderResponseMetadata(), lease = null, providerStarted = true) {
+        const usage = embeddingTokenUsage(response);
+        const costUSD = providerStarted
+            ? calculateAIRequestCostUSD(tracked.model, usage)
+            : 0;
+        tracked.aiRequest.assign({
+            response: compactEmbeddingResponse(response),
+            providerRequestId: metadata.providerRequestId,
+            providerProcessingMs: metadata.providerProcessingMs,
+            rateLimitBucket: lease?.bucket ?? null,
+            rateLimitSnapshot: metadata.rateLimitSnapshot,
+            status: AI_REQUEST_STATUS.failed,
+            completedAt: new Date(),
+            durationMs: Date.now() - tracked.startTimeMs,
+            inputTokens: usage.inputTokens,
+            outputTokens: usage.outputTokens,
+            totalTokens: usage.totalTokens,
+            reasoningTokens: usage.reasoningTokens,
+            cachedTokens: usage.cachedTokens,
+            cacheWriteTokens: usage.cacheWriteTokens,
+            costUSD,
+            knownCostUSD: costUSD ?? 0,
+            errorCode: responseErrorCode(response),
+            errorMessage: message,
+            metadata: {
+                ...(tracked.aiRequest.metadata ?? {}),
+                providerStarted,
+            },
+        });
+        await saveTerminalAiRequest(tracked.aiRequest);
+    }
+    /**
+     * Create a pending request row for an image generation call.
+     *
+     * @param request - Provider request payload.
+     * @param options - Logging context with a required operation.
+     * @param model - Image model used for the request.
+     * @returns Tracked image request state.
+     */
+    async startTrackedImageRequest(request, options, model) {
+        const user = options.user ?? this.activeUser();
+        const userId = userRecordId(user);
+        const scopeId = scopeRecordId(options[this.scopeField] ?? null);
+        const conversation = await this.resolveOptionalConversation(options.conversation);
+        const startTimeMs = Date.now();
+        const aiRequest = await new this.models.request({
+            conversation,
+            parentAiRequest: options.parentAiRequest ?? null,
+            user: userId,
+            [this.scopeField]: scopeId,
+            provider: AI_PROVIDER.openai,
+            model,
+            operation: options.operation,
+            status: AI_REQUEST_STATUS.pending,
+            request,
+            metadata: options.metadata ?? null,
+            startedAt: new Date(),
+        }).save();
+        return {
+            aiRequest,
+            startTimeMs,
+            model,
+        };
+    }
+    /**
+     * Mark an image request completed with its app-owned storage reference.
+     *
+     * @param tracked - Tracked image request state.
+     * @param storedResponse - Storage path, id, or record returned by the caller.
+     * @param providerResponse - Provider payload used to normalize token usage.
+     * @param metadata - Parsed provider response headers.
+     * @param lease - Active rate-limit lease.
+     */
+    async completeTrackedImageRequest(tracked, storedResponse, providerResponse, metadata = emptyProviderResponseMetadata(), lease = null) {
+        const usage = imageTokenUsage(providerResponse);
+        const costUSD = calculateAIImageRequestCostUSD(tracked.model, usage);
+        tracked.aiRequest.assign({
+            response: storedResponse,
+            providerRequestId: metadata.providerRequestId,
+            providerProcessingMs: metadata.providerProcessingMs,
+            rateLimitBucket: lease?.bucket ?? null,
+            rateLimitSnapshot: metadata.rateLimitSnapshot,
+            status: AI_REQUEST_STATUS.completed,
+            completedAt: new Date(),
+            durationMs: Date.now() - tracked.startTimeMs,
+            inputTokens: usage.inputTokens,
+            outputTokens: usage.outputTokens,
+            totalTokens: usage.totalTokens,
+            reasoningTokens: usage.reasoningTokens,
+            cachedTokens: usage.cachedTokens,
+            cacheWriteTokens: usage.cacheWriteTokens,
+            costUSD,
+            knownCostUSD: costUSD ?? 0,
+        });
+        await saveTerminalAiRequest(tracked.aiRequest);
+    }
+    /**
+     * Mark an image request failed and keep compact provider metadata.
+     *
+     * @param tracked - Tracked image request state.
+     * @param response - Provider response payload, when available.
+     * @param message - Failure message to store.
+     * @param metadata - Parsed provider response headers.
+     * @param lease - Active rate-limit lease.
+     * @param providerStarted - Whether execution crossed the external provider boundary.
+     */
+    async failTrackedImageRequest(tracked, response, message, metadata = emptyProviderResponseMetadata(), lease = null, providerStarted = true) {
+        const usage = imageTokenUsage(response);
+        const costUSD = providerStarted
+            ? calculateAIImageRequestCostUSD(tracked.model, usage)
+            : 0;
+        tracked.aiRequest.assign({
+            response: compactImageResponse(response),
+            providerRequestId: metadata.providerRequestId,
+            providerProcessingMs: metadata.providerProcessingMs,
+            rateLimitBucket: lease?.bucket ?? null,
+            rateLimitSnapshot: metadata.rateLimitSnapshot,
+            status: AI_REQUEST_STATUS.failed,
+            completedAt: new Date(),
+            durationMs: Date.now() - tracked.startTimeMs,
+            inputTokens: usage.inputTokens,
+            outputTokens: usage.outputTokens,
+            totalTokens: usage.totalTokens,
+            reasoningTokens: usage.reasoningTokens,
+            cachedTokens: usage.cachedTokens,
+            cacheWriteTokens: usage.cacheWriteTokens,
+            costUSD,
+            knownCostUSD: costUSD ?? 0,
+            errorCode: responseErrorCode(response),
+            errorMessage: message,
+            metadata: {
+                ...(tracked.aiRequest.metadata ?? {}),
+                providerStarted,
+            },
+        });
+        await saveTerminalAiRequest(tracked.aiRequest);
+    }
+    /**
+     * Best-effort lookup of the authenticated application user.
+     */
+    activeUser() {
+        try {
+            return app().auth.user;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * API key from explicit options or OPENAI_API_KEY.
+     */
+    apiKey() {
+        return this.options.apiKey ?? process.env.OPENAI_API_KEY ?? '';
+    }
+    /**
+     * Return the configured API key or fail with the public configuration error.
+     */
+    requireApiKey() {
+        const apiKey = this.apiKey();
+        if (!apiKey) {
+            throw new AIConfigurationError();
+        }
+        return apiKey;
+    }
+    /**
+     * Creates an SDK adapter that observes and releases capacity for each HTTP request.
+     *
+     * @param attempt - Resolved provider connection and model.
+     * @param initialLease - Optional preflight reservation consumed by the first request.
+     * @returns SDK provider using the service's transport and rate-limit lifecycle.
+     */
+    createAgentProvider(attempt, initialLease = null) {
+        return new OpenAIProvider({
+            openAIClient: new OpenAI({ apiKey: attempt.apiKey, baseURL: attempt.baseUrl, fetch: this.agentFetcher(attempt, initialLease), timeout: this.options.timeoutMs ?? 60_000, maxRetries: 0 }),
+            useResponses: attempt.supportsResponsesApi,
+        });
+    }
+    /**
+     * Reserves each SDK model turn and observes headers before streaming or tool execution.
+     *
+     * The agent's preflight lease covers only its first HTTP request. Releasing it
+     * when headers arrive lets nested tools and concurrent agents use the bucket,
+     * including providers that omit capacity headers. Later turns reserve again.
+     * Transport and persistence failures still release their active reservation.
+     *
+     * @param attempt - Provider and model selected for this SDK attempt.
+     * @param initialLease - First-request reservation, if acquired by the agent.
+     * @returns Transport that maintains provider capacity and request diagnostics.
+     */
+    agentFetcher(attempt, initialLease) {
+        let pendingLease = initialLease;
+        const transport = this.fetcher();
+        return async (url, init) => {
+            const aiRequest = aiExecutionContext.getStore()?.aiRequest ?? null;
+            const lease = pendingLease ?? await this.acquireRateLimit({
+                provider: attempt.provider,
+                endpoint: responsesRateLimitEndpoint(),
+                model: attempt.model,
+                operation: aiRequest?.operation ?? 'agents.run.stream',
+                estimatedTokens: estimateTokensFromText(typeof init?.body === 'string' ? init.body : ''),
+                aiRequest,
+            });
+            pendingLease = null;
+            let response = null;
+            try {
+                response = await transport(url, init);
+                const metadata = providerResponseMetadata(response.headers);
+                await this.observeRateLimit(lease, metadata);
+                if (aiRequest) {
+                    aiRequest.assign({
+                        providerRequestId: metadata.providerRequestId,
+                        providerProcessingMs: metadata.providerProcessingMs,
+                        rateLimitBucket: lease?.bucket ?? null,
+                        rateLimitSnapshot: metadata.rateLimitSnapshot,
+                    });
+                    await aiRequest.save();
+                }
+                return response;
+            }
+            catch (error) {
+                await response?.body?.cancel().catch(() => { });
+                throw error;
+            }
+            finally {
+                await this.releaseRateLimit(lease);
+            }
+        };
+    }
+    /**
+     * Fetch implementation used by provider calls.
+     */
+    fetcher() {
+        const transport = this.options.fetch || fetch;
+        return (url, init) => transport(url, { ...init, signal: init?.signal ?? AbortSignal.timeout(this.options.timeoutMs ?? 60_000) });
+    }
+    /**
+     * Responses API base URL with trailing slashes removed.
+     */
+    baseUrl() {
+        return (this.options.baseUrl ?? process.env.OPENAI_BASE_URL ?? 'https://api.openai.com/v1')
+            .replace(/\/+$/g, '');
+    }
+    /**
+     * Full Embeddings API endpoint URL.
+     */
+    embeddingsUrl() {
+        return `${this.baseUrl()}/embeddings`;
+    }
+    /**
+     * Full Images API generations endpoint URL.
+     */
+    imagesUrl() {
+        return `${this.baseUrl()}/images/generations`;
+    }
+    /**
+     * Reserves provider capacity when rate limiting is enabled.
+     *
+     * @param input - Endpoint, model, operation, and estimated token cost.
+     * @returns Active rate-limit lease, or null when no limiter is configured.
+     */
+    async acquireRateLimit(input) {
+        return this.rateLimiter
+            ? await this.rateLimiter.acquire(input)
+            : null;
+    }
+    /**
+     * Applies provider header metadata to the bucket and releases the lease.
+     *
+     * @param lease - Active rate-limit lease.
+     * @param metadata - Parsed provider response headers.
+     */
+    async observeRateLimit(lease, metadata) {
+        if (!this.rateLimiter || !lease)
+            return;
+        await this.rateLimiter.observe(lease, metadata);
+    }
+    /**
+     * Attaches a saved request row to an existing reservation.
+     *
+     * @param lease - Active rate-limit lease.
+     * @param aiRequest - Saved request row to link.
+     */
+    async attachRateLimitRequest(lease, aiRequest) {
+        if (!lease?.reservation || !aiRequest)
+            return;
+        lease.reservation.assign({
+            aiRequest,
+        });
+        await lease.reservation.save();
+    }
+    /**
+     * Releases a rate-limit reservation after local failures.
+     *
+     * @param lease - Active rate-limit lease.
+     */
+    async releaseRateLimit(lease) {
+        if (!this.rateLimiter || !lease)
+            return;
+        await this.rateLimiter.release(lease);
+    }
+    /**
+     * Generate one image and track the provider request by default.
+     *
+     * Callers can provide a storage callback to save the returned image bytes.
+     * The callback result is stored on `AiRequest.response`, which keeps the
+     * audit row pointed at the app-owned file id/path without persisting raw
+     * image bytes in the database.
+     *
+     * @param input - Prompt and image generation settings.
+     * @param options - Optional request context and storage callback.
+     * @returns Generated image bytes, model, tracking id, and storage reference.
+     */
+    async generateImage(input, options = {}) {
+        options = scopedAiOptions(options, this.scopeField);
+        assertIndependentUsage(options);
+        const apiKey = this.requireApiKey();
+        const model = input.model || this.config('ImageGeneration', 'gpt-image-2');
+        const prompt = input.prompt.replace(/\s+/g, ' ').trim();
+        const outputFormat = input.outputFormat ?? 'png';
+        const operation = options.operation ?? 'images.generate';
+        const request = {
+            model,
+            prompt,
+            size: input.size,
+            quality: input.quality,
+            output_format: outputFormat,
+            user: input.user ?? undefined,
+        };
+        let tracked = null;
+        let lease = null;
+        let trackedSettled = false;
+        let providerStarted = false;
+        if (!prompt)
+            throw new Error('Prompt is required for image generation.');
+        try {
+            tracked = options.saveAiResponse !== false
+                ? await this.startTrackedImageRequest(request, {
+                    ...options,
+                    operation,
+                }, model)
+                : null;
+            await this.checkAllowance({
+                provider: AI_PROVIDER.openai,
+                endpoint: imagesRateLimitEndpoint(),
+                model,
+                operation,
+                user: options.user ?? input.user ?? null,
+                scope: options[this.scopeField] ?? null,
+                aiRequest: tracked?.aiRequest ?? null,
+                estimatedTokens: estimatedImageTokens(input),
+                usage: options.usage ?? null,
+                metadata: {
+                    ...(options.metadata ?? {}),
+                    imageSize: input.size ?? null,
+                    imageQuality: input.quality ?? null,
+                    outputFormat,
+                },
+            });
+            lease = await this.acquireRateLimit({
+                endpoint: imagesRateLimitEndpoint(),
+                model,
+                operation,
+                estimatedTokens: estimatedImageTokens(input),
+                aiRequest: tracked?.aiRequest ?? null,
+            });
+            await this.attachRateLimitRequest(lease, tracked?.aiRequest ?? null);
+            providerStarted = true;
+            const response = await this.fetcher()(this.imagesUrl(), {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${apiKey}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify(request),
+            });
+            const metadata = providerResponseMetadata(response.headers);
+            const payload = await response.json().catch(() => null);
+            if (!response.ok) {
+                const message = responseErrorMessage(payload) || `OpenAI image request failed with HTTP ${response.status}.`;
+                const deferred = isRateLimitFailure(response.status, payload)
+                    ? rateLimitDeferredError(lease, metadata, message)
+                    : null;
+                if (tracked) {
+                    await this.failTrackedImageRequest(tracked, payload, message, metadata, lease);
+                    trackedSettled = true;
+                }
+                await this.observeRateLimit(lease, metadata);
+                lease = null;
+                if (deferred)
+                    throw deferred;
+                throw new AIRequestError(message, responseErrorCode(payload));
+            }
+            const b64Json = imageBase64(payload);
+            if (!b64Json) {
+                const message = 'OpenAI did not return image data.';
+                if (tracked) {
+                    await this.failTrackedImageRequest(tracked, payload, message, metadata, lease);
+                    trackedSettled = true;
+                }
+                await this.observeRateLimit(lease, metadata);
+                lease = null;
+                throw new AIRequestError(message, responseErrorCode(payload));
+            }
+            let stored = null;
+            try {
+                stored = options.store
+                    ? await options.store({
+                        b64Json,
+                        aiRequest: tracked?.aiRequest ?? null,
+                        aiRequestId: tracked?.aiRequest.id ? String(tracked.aiRequest.id) : null,
+                        model,
+                        prompt,
+                        size: input.size ?? null,
+                        quality: input.quality ?? null,
+                        outputFormat,
+                        providerResponse: compactImageResponse(payload),
+                    })
+                    : null;
+            }
+            catch (error) {
+                if (tracked) {
+                    await this.failTrackedImageRequest(tracked, payload, errorMessage(error), metadata, lease);
+                    trackedSettled = true;
+                }
+                await this.observeRateLimit(lease, metadata);
+                lease = null;
+                throw error;
+            }
+            if (tracked) {
+                await this.completeTrackedImageRequest(tracked, imageStoredResponse(stored) ?? compactImageResponse(payload), payload, metadata, lease);
+                trackedSettled = true;
+            }
+            await this.observeRateLimit(lease, metadata);
+            lease = null;
+            return {
+                b64Json,
+                model,
+                aiRequestId: tracked?.aiRequest.id ? String(tracked.aiRequest.id) : null,
+                stored,
+            };
+        }
+        catch (error) {
+            if (error instanceof AIUsagePersistenceError) {
+                try {
+                    await this.releaseRateLimit(lease);
+                }
+                finally {
+                    throw error;
+                }
+            }
+            await this.releaseRateLimit(lease);
+            if (tracked && !trackedSettled && !(error instanceof AIRequestError) && !(error instanceof AIRateLimitDeferredError)) {
+                await this.failTrackedImageRequest(tracked, null, errorMessage(error), emptyProviderResponseMetadata(), lease, providerStarted);
+            }
+            if (error instanceof AIRateLimitDeferredError)
+                throw error;
+            if (error instanceof AIAllowanceExceededError)
+                throw error;
+            if (error instanceof AIRequestError)
+                throw error;
+            throw new AIRequestError(errorMessage(error));
+        }
+    }
+    /**
+     * Generate an embedding vector and track provider usage by default.
+     *
+     * @param input - Text to embed.
+     * @param model - OpenAI embedding model to use.
+     * @param options - Optional AI request logging context.
+     * @returns Embedding vector, model, and saved request id when tracking is enabled.
+     */
+    async generateEmbedding(input, model = 'text-embedding-3-small', options = {}) {
+        options = scopedAiOptions(options, this.scopeField);
+        assertIndependentUsage(options);
+        if (!input)
+            throw new Error('Input is required for embedding generation.');
+        const apiKey = this.requireApiKey();
+        const operation = options.operation ?? 'embeddings.create';
+        const request = {
+            model,
+            input,
+            encoding_format: 'float',
+        };
+        let tracked = null;
+        let lease = null;
+        let trackedSettled = false;
+        let providerStarted = false;
+        try {
+            lease = await this.acquireRateLimit({
+                endpoint: embeddingsRateLimitEndpoint(),
+                model,
+                operation,
+                estimatedTokens: estimatedEmbeddingTokens(input),
+                aiRequest: null,
+            });
+            tracked = options.saveAiResponse !== false
+                ? await this.startTrackedEmbeddingRequest(request, {
+                    ...options,
+                    operation,
+                }, model)
+                : null;
+            await this.checkAllowance({
+                provider: AI_PROVIDER.openai,
+                endpoint: embeddingsRateLimitEndpoint(),
+                model,
+                operation,
+                user: options.user ?? this.activeUser(),
+                scope: options[this.scopeField] ?? null,
+                aiRequest: tracked?.aiRequest ?? null,
+                estimatedTokens: estimatedEmbeddingTokens(input),
+                usage: options.usage ?? null,
+                metadata: options.metadata ?? null,
+            });
+            await this.attachRateLimitRequest(lease, tracked?.aiRequest ?? null);
+            providerStarted = true;
+            const response = await this.fetcher()(this.embeddingsUrl(), {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${apiKey}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify(request),
+            });
+            const metadata = providerResponseMetadata(response.headers);
+            const payload = await response.json().catch(() => null);
+            if (!response.ok) {
+                const message = responseErrorMessage(payload) || `OpenAI embedding request failed with HTTP ${response.status}.`;
+                const deferred = isRateLimitFailure(response.status, payload)
+                    ? rateLimitDeferredError(lease, metadata, message)
+                    : null;
+                if (tracked) {
+                    await this.failTrackedEmbeddingRequest(tracked, payload, message, metadata, lease);
+                    trackedSettled = true;
+                }
+                await this.observeRateLimit(lease, metadata);
+                lease = null;
+                if (deferred)
+                    throw deferred;
+                throw new AIRequestError(message, responseErrorCode(payload));
+            }
+            const vector = payload?.data?.[0]?.embedding;
+            if (!Array.isArray(vector)) {
+                const message = 'OpenAI did not return a valid embedding.';
+                if (tracked) {
+                    await this.failTrackedEmbeddingRequest(tracked, payload, message, metadata, lease);
+                    trackedSettled = true;
+                }
+                await this.observeRateLimit(lease, metadata);
+                lease = null;
+                throw new AIRequestError(message, responseErrorCode(payload));
+            }
+            if (tracked) {
+                await this.completeTrackedEmbeddingRequest(tracked, payload, metadata, lease);
+                trackedSettled = true;
+            }
+            await this.observeRateLimit(lease, metadata);
+            lease = null;
+            return {
+                vector,
+                model,
+                aiRequestId: tracked?.aiRequest.id ? String(tracked.aiRequest.id) : null,
+            };
+        }
+        catch (error) {
+            if (error instanceof AIUsagePersistenceError) {
+                try {
+                    await this.releaseRateLimit(lease);
+                }
+                finally {
+                    throw error;
+                }
+            }
+            await this.releaseRateLimit(lease);
+            if (tracked && !trackedSettled && !(error instanceof AIRequestError) && !(error instanceof AIRateLimitDeferredError)) {
+                await this.failTrackedEmbeddingRequest(tracked, null, errorMessage(error), emptyProviderResponseMetadata(), lease, providerStarted);
+            }
+            if (error instanceof AIRateLimitDeferredError)
+                throw error;
+            if (error instanceof AIRequestError)
+                throw error;
+            throw new AIRequestError(errorMessage(error));
+        }
+    }
+}
+/**
+ * Makes one already-assigned terminal AI request outcome durable.
+ *
+ * Retries update the same model instance without changing its payload, status,
+ * usage, or cost. This prevents a transient database acknowledgement failure
+ * from causing paid provider work to be replayed or rewritten as usage-free.
+ *
+ * @param aiRequest - Request whose exact terminal fields were assigned by the caller.
+ * @throws {AIUsagePersistenceError} When all bounded save attempts fail.
+ */
+async function saveTerminalAiRequest(aiRequest) {
+    let persistenceCause = null;
+    for (let attempt = 0; attempt < TERMINAL_AI_REQUEST_SAVE_ATTEMPTS; attempt++) {
+        try {
+            await aiRequest.save();
+            return;
+        }
+        catch (error) {
+            persistenceCause = error;
+        }
+    }
+    throw new AIUsagePersistenceError(aiRequest.id ? String(aiRequest.id) : null, persistenceCause);
+}
+export { AIAllowanceExceededError, AIConfigurationError, AIRequestError } from './AIErrors.js';
+export { AI_PROVIDER };
+/**
+ * Empty provider metadata used when a request fails before reaching OpenAI.
+ *
+ * @returns Null-valued provider metadata.
+ */
+function emptyProviderResponseMetadata() {
+    return {
+        providerRequestId: null,
+        providerProcessingMs: null,
+        rateLimitSnapshot: null,
+    };
+}
+/**
+ * Builds the optional Responses API max_output_tokens payload.
+ *
+ * @param maxOutputTokens - Optional maximum output token count.
+ * @returns Request fragment to merge into a provider payload.
+ */
+function maxOutputTokensPayload(maxOutputTokens) {
+    return typeof maxOutputTokens === 'number' && Number.isFinite(maxOutputTokens) && maxOutputTokens > 0
+        ? {
+            max_output_tokens: Math.trunc(maxOutputTokens),
+        }
+        : {};
+}
+/**
+ * Estimates request size before OpenAI returns exact usage.
+ *
+ * @param input - Text generation input.
+ * @param request - Provider request payload.
+ * @returns Conservative token estimate for reservation accounting.
+ */
+function estimatedResponseTokens(input, request) {
+    const outputEstimate = typeof input.maxOutputTokens === 'number' && Number.isFinite(input.maxOutputTokens) && input.maxOutputTokens > 0
+        ? Math.trunc(input.maxOutputTokens)
+        : 0;
+    const text = [
+        input.instructions,
+        input.input,
+        JSON.stringify(request.text ?? ''),
+    ].join('\n');
+    return estimateTokensFromText(text) + outputEstimate;
+}
+/**
+ * Estimates embedding input size before OpenAI returns exact usage.
+ *
+ * @param input - Text being embedded.
+ * @returns Approximate token count.
+ */
+function estimatedEmbeddingTokens(input) {
+    return estimateTokensFromText(input);
+}
+/**
+ * Estimates image request size before OpenAI returns any usage metadata.
+ *
+ * @param input - Image generation request.
+ * @returns Approximate prompt token count.
+ */
+function estimatedImageTokens(input) {
+    return estimateTokensFromText(input.prompt);
+}
+/**
+ * Builds the sanitized audit record for one failed provider attempt.
+ *
+ * @param attempt - Provider attempt that failed.
+ * @param startMs - Epoch milliseconds when the attempt started.
+ * @param message - Human-readable failure message.
+ * @param status - HTTP status, when the provider responded.
+ * @param code - Provider error code, when supplied.
+ * @returns Attempt failure entry for AiRequest metadata.
+ */
+function providerAttemptFailure(attempt, startMs, message, status, code) {
+    return {
+        provider: attempt.provider,
+        model: attempt.model,
+        status,
+        code,
+        message,
+        durationMs: Date.now() - startMs,
+    };
+}
+/**
+ * Builds the sanitized audit record for a thrown provider attempt failure.
+ *
+ * @param attempt - Provider attempt that failed.
+ * @param startMs - Epoch milliseconds when the attempt started.
+ * @param error - Thrown value from the attempt.
+ * @returns Attempt failure entry for AiRequest metadata.
+ */
+function providerAttemptFailureFromError(attempt, startMs, error) {
+    const details = openAIProviderError(error);
+    return providerAttemptFailure(attempt, startMs, details.message, details.status, details.code);
+}
+/**
+ * Merges failed provider attempts onto tracked request metadata for auditing.
+ *
+ * The caller is responsible for saving the row; complete/fail helpers persist
+ * the assignment together with their own fields.
+ *
+ * @param aiRequest - Tracked request row.
+ * @param failures - Failed attempts collected so far.
+ */
+function attachProviderAttempts(aiRequest, failures) {
+    if (failures.length === 0)
+        return;
+    aiRequest.assign({
+        metadata: {
+            ...(aiRequest.metadata ?? {}),
+            providerAttempts: failures,
+        },
+    });
+}
+/**
+ * Detects provider failures that should be retried after a rate-limit reset.
+ *
+ * @param status - HTTP response status.
+ * @param payload - Provider response payload.
+ * @returns True when the provider indicates a rate-limit failure.
+ */
+function isRateLimitFailure(status, payload) {
+    if (isOpenAIQuotaError(payload))
+        return false;
+    const code = responseErrorCode(payload);
+    return code === 'rate_limit_exceeded' || (status === 429 && code === null);
+}
+/**
+ * Converts a provider rate-limit response into a queue-compatible deferral.
+ *
+ * @param lease - Active limiter lease, when one exists.
+ * @param metadata - Parsed provider response metadata.
+ * @param message - Provider error message.
+ * @returns Queue retry-later error.
+ */
+function rateLimitDeferredError(lease, metadata, message) {
+    return new AIRateLimitDeferredError(rateLimitRetryDelaySeconds(metadata), lease?.bucketKey ?? 'openai:unknown', rateLimitResetAt(metadata), message);
+}
+/**
+ * Chooses the latest known reset delay from provider rate-limit headers.
+ *
+ * @param metadata - Parsed provider response metadata.
+ * @returns Delay in whole seconds.
+ */
+function rateLimitRetryDelaySeconds(metadata) {
+    const snapshot = metadata.rateLimitSnapshot;
+    const resetAfterMs = Math.max(0, snapshot?.requestsResetAfterMs ?? 0, snapshot?.tokensResetAfterMs ?? 0, snapshot?.projectTokensResetAfterMs ?? 0);
+    return resetAfterMs > 0
+        ? Math.max(1, Math.ceil(resetAfterMs / 1000))
+        : 60;
+}
+/**
+ * Chooses the latest absolute reset time from provider rate-limit headers.
+ *
+ * @param metadata - Parsed provider response metadata.
+ * @returns Reset date or null when unavailable.
+ */
+function rateLimitResetAt(metadata) {
+    const snapshot = metadata.rateLimitSnapshot;
+    const values = [
+        snapshot?.requestsResetAt,
+        snapshot?.tokensResetAt,
+        snapshot?.projectTokensResetAt,
+    ]
+        .map(value => value ? Date.parse(value) : NaN)
+        .filter(value => Number.isFinite(value));
+    if (values.length === 0)
+        return null;
+    return new Date(Math.max(...values));
+}
+/**
+ * Extract token counts from a Responses API payload.
+ */
+/**
+ * Resolves the exact text-request cost from the provider's trusted source.
+ *
+ * Official OpenAI requests use the framework model rate card. Providers that
+ * resell or dynamically route models must report the amount actually billed;
+ * when they omit it, the request remains unpriced instead of using an unsafe
+ * model-name estimate.
+ *
+ * @param provider - Provider that executed the request.
+ * @param model - Model recorded for the provider request.
+ * @param usage - Normalized provider token usage.
+ * @param payload - Raw provider response containing billed-cost extensions.
+ * @returns Exact billed cost in USD, or null when it cannot be established.
+ */
+function textRequestCostUSD(provider, model, usage, payload) {
+    if (provider === AI_PROVIDER.openai) {
+        return calculateAIRequestCostUSD(model, usage);
+    }
+    return providerReportedCostUSD(provider, payload);
+}
+/**
+ * Normalizes token usage from a Responses API payload.
+ *
+ * @param payload - Provider response payload, or null when unavailable.
+ * @returns Token counts with absent dimensions preserved as null.
+ */
+function tokenUsage(payload) {
+    const usage = asRecord(payload?.usage);
+    const inputDetails = asRecord(usage?.input_tokens_details);
+    const outputDetails = asRecord(usage?.output_tokens_details);
+    return {
+        inputTokens: integerValue(usage?.input_tokens),
+        outputTokens: integerValue(usage?.output_tokens),
+        totalTokens: integerValue(usage?.total_tokens),
+        reasoningTokens: integerValue(outputDetails?.reasoning_tokens),
+        cachedTokens: integerValue(inputDetails?.cached_tokens),
+        cacheWriteTokens: integerValue(inputDetails?.cache_write_tokens),
+    };
+}
+/**
+ * Extract token counts from an Embeddings API payload.
+ */
+function embeddingTokenUsage(payload) {
+    const usage = asRecord(payload?.usage);
+    return {
+        inputTokens: integerValue(usage?.prompt_tokens),
+        outputTokens: null,
+        totalTokens: integerValue(usage?.total_tokens),
+        reasoningTokens: null,
+        cachedTokens: null,
+        cacheWriteTokens: null,
+    };
+}
+/**
+ * Extract token counts from an Images API payload.
+ *
+ * The current image helper only sends text-to-image generation requests, so
+ * aggregate input tokens can be treated as text tokens when modality details are
+ * absent. Image output tokens fall back to the aggregate output count because
+ * the Images API response payload contains image output only.
+ *
+ * @param payload - Provider response payload.
+ * @returns Normalized token usage for audit and cost calculation.
+ */
+function imageTokenUsage(payload) {
+    const usage = asRecord(payload?.usage);
+    const inputDetails = asRecord(usage?.input_tokens_details);
+    const outputDetails = asRecord(usage?.output_tokens_details);
+    const cachedDetails = asRecord(inputDetails?.cached_tokens_details);
+    const inputTokens = integerValue(usage?.input_tokens);
+    const outputTokens = integerValue(usage?.output_tokens);
+    const cachedTokens = integerValue(inputDetails?.cached_tokens);
+    return {
+        inputTokens,
+        outputTokens,
+        totalTokens: integerValue(usage?.total_tokens),
+        reasoningTokens: null,
+        cachedTokens,
+        cacheWriteTokens: null,
+        inputTextTokens: integerValue(inputDetails?.text_tokens) ?? inputTokens,
+        inputImageTokens: integerValue(inputDetails?.image_tokens) ?? 0,
+        outputImageTokens: integerValue(outputDetails?.image_tokens) ?? outputTokens,
+        cachedTextTokens: integerValue(inputDetails?.cached_text_tokens) ?? integerValue(cachedDetails?.text_tokens) ?? cachedTokens,
+        cachedImageTokens: integerValue(inputDetails?.cached_image_tokens) ?? integerValue(cachedDetails?.image_tokens),
+    };
+}
+/**
+ * Store provider metadata without duplicating the full embedding vector.
+ */
+function compactEmbeddingResponse(payload) {
+    if (!payload)
+        return null;
+    return {
+        ...payload,
+        data: Array.isArray(payload.data)
+            ? payload.data.map(item => compactEmbeddingDataItem(item))
+            : payload.data,
+    };
+}
+/**
+ * Replace embedding vectors with their dimensionality for request auditing.
+ */
+function compactEmbeddingDataItem(item) {
+    const record = asRecord(item) ?? {};
+    const embedding = record.embedding;
+    return {
+        ...record,
+        embedding: Array.isArray(embedding)
+            ? {
+                dimensions: embedding.length,
+            }
+            : embedding,
+    };
+}
+/**
+ * Extracts the first base64 image payload from an Images API response.
+ *
+ * @param payload - Provider response payload.
+ * @returns Base64 image bytes, or null when unavailable.
+ */
+function imageBase64(payload) {
+    const value = payload?.data?.[0]?.b64_json;
+    return typeof value === 'string' && value.trim() ? value : null;
+}
+/**
+ * Store image provider metadata without duplicating raw generated bytes.
+ *
+ * @param payload - Provider response payload.
+ * @returns Compact response safe for AiRequest.response.
+ */
+function compactImageResponse(payload) {
+    if (!payload)
+        return null;
+    return {
+        ...payload,
+        data: Array.isArray(payload.data)
+            ? payload.data.map(item => compactImageDataItem(item))
+            : payload.data,
+    };
+}
+/**
+ * Replaces base64 image bytes with byte-count metadata.
+ *
+ * @param item - Provider image response item.
+ * @returns Compact image response item.
+ */
+function compactImageDataItem(item) {
+    const record = asRecord(item) ?? {};
+    const base64 = record.b64_json;
+    return {
+        ...record,
+        b64_json: typeof base64 === 'string'
+            ? {
+                encodedLength: base64.length,
+            }
+            : base64,
+    };
+}
+/**
+ * Normalizes caller storage references for JSON-field persistence.
+ *
+ * @param value - Storage callback result.
+ * @returns JSON-safe response value for AiRequest.response.
+ */
+function imageStoredResponse(value) {
+    if (typeof value === 'string') {
+        return {
+            path: value,
+        };
+    }
+    return value;
+}
+/**
+ * Extract the provider error code from a failed Responses API payload.
+ */
+function responseErrorCode(payload) {
+    const error = asRecord(asRecord(payload)?.error);
+    const code = error?.code;
+    return typeof code === 'string' && code.trim() ? code.trim() : null;
+}
+/**
+ * Convert finite numeric token counts to integers and reject all other values.
+ */
+function integerValue(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return null;
+    return Math.trunc(value);
+}
+/**
+ * Prevents one provider request from being charged both as a child and directly.
+ *
+ * @param options - Provider request logging and allowance options.
+ * @throws {Error} When a child request also supplies an explicit usage charge.
+ */
+function assertIndependentUsage(options) {
+    if (options.parentAiRequest && options.usage) {
+        throw new Error('Nested AI requests cannot carry an independent usage charge.');
+    }
+}
+/**
+ * Narrow unknown JSON values to plain object-like records.
+ */
+function asRecord(value) {
+    return value !== null && typeof value === 'object'
+        ? value
+        : null;
+}
+/**
+ * Safe display message for an unknown thrown value.
+ */
+function errorMessage(error) {
+    return error instanceof Error ? error.message : 'Unexpected AI request error.';
+}
+/**
+ * Normalize a user record or id into the string id stored on AI rows.
+ */
+function userRecordId(user) {
+    if (typeof user === 'string')
+        return user;
+    const id = user?.id;
+    return id === null || id === undefined ? null : String(id);
+}
+/**
+ * Normalize an application scope record or id into the string id stored on AI rows.
+ */
+function scopeRecordId(scope) {
+    if (typeof scope === 'string')
+        return scope;
+    const id = scope?.id;
+    return id === null || id === undefined ? null : String(id);
+}