@db3.ai/app 0.1.0-beta.1

package/dist/ai/ProviderCosts.js

@@ -0,0 +1,108 @@
+import { AI_PROVIDER } from './contracts/AI.js';
+const USD_COST_PRECISION = 100_000_000;
+const XAI_USD_TICKS_PER_DOLLAR = 10_000_000_000;
+/**
+ * Extracts the authoritative billed USD cost from one provider payload.
+ *
+ * OpenRouter returns dollars in `usage.cost`. xAI returns integer USD ticks in
+ * `usage.cost_in_usd_ticks`, where ten billion ticks equal one US dollar.
+ * Other providers intentionally return null so locally estimated prices cannot
+ * be mistaken for the amount actually charged by an intermediary.
+ *
+ * @param provider - Provider that returned the payload.
+ * @param payload - Response object containing the provider usage block.
+ * @returns Provider-reported billed cost in USD, or null when unavailable.
+ */
+export function providerReportedCostUSD(provider, payload) {
+    const usage = recordValue(recordValue(payload)?.usage);
+    if (!usage)
+        return null;
+    if (provider === AI_PROVIDER.openrouter) {
+        return validNonNegativeNumber(usage.cost);
+    }
+    if (provider === AI_PROVIDER.xai) {
+        const ticks = validNonNegativeNumber(usage.cost_in_usd_ticks);
+        return ticks === null ? null : roundCostUSD(ticks / XAI_USD_TICKS_PER_DOLLAR);
+    }
+    return null;
+}
+/**
+ * Builds a deduplicatable cost entry for one terminal provider response.
+ *
+ * @param provider - Provider that returned the response.
+ * @param payload - Response object containing provider usage.
+ * @param responseId - Stable provider response identifier.
+ * @returns Captured provider cost, or null when the id or billed cost is absent.
+ */
+export function providerReportedCost(provider, payload, responseId) {
+    if (typeof responseId !== 'string' || !responseId.trim())
+        return null;
+    const costUSD = providerReportedCostUSD(provider, payload);
+    if (costUSD === null)
+        return null;
+    return {
+        responseId,
+        costUSD,
+        source: provider === AI_PROVIDER.xai
+            ? 'xai_usage_cost_in_usd_ticks'
+            : 'openrouter_usage_cost',
+    };
+}
+/**
+ * Summarizes unique provider costs and fails closed when coverage is incomplete.
+ *
+ * @param costs - Cost entries keyed by provider response id.
+ * @param expectedRequestCount - Provider request count reported by the SDK.
+ * @returns Known subtotal plus an exact total only when every request is covered.
+ */
+export function summarizeProviderReportedCosts(costs, expectedRequestCount) {
+    const entries = [...costs.values()];
+    const knownCostUSD = roundCostUSD(entries.reduce((total, entry) => total + entry.costUSD, 0));
+    const normalizedExpectedCount = Number.isFinite(expectedRequestCount) && expectedRequestCount >= 0
+        ? Math.trunc(expectedRequestCount)
+        : 0;
+    const complete = normalizedExpectedCount > 0 && entries.length === normalizedExpectedCount;
+    return {
+        knownCostUSD,
+        costUSD: complete ? knownCostUSD : null,
+        reportedRequestCount: entries.length,
+        expectedRequestCount: normalizedExpectedCount,
+        sources: [...new Set(entries.map(entry => entry.source))],
+    };
+}
+/**
+ * Converts a provider numeric field into a safe non-negative number.
+ *
+ * @param value - Unknown numeric value from a provider response.
+ * @returns Rounded numeric value, or null when missing, negative, or invalid.
+ */
+function validNonNegativeNumber(value) {
+    const parsed = typeof value === 'number'
+        ? value
+        : typeof value === 'string' && value.trim()
+            ? Number(value)
+            : null;
+    if (parsed === null || !Number.isFinite(parsed) || parsed < 0)
+        return null;
+    return roundCostUSD(parsed);
+}
+/**
+ * Narrows an unknown value to a plain record.
+ *
+ * @param value - Unknown provider payload value.
+ * @returns Record value, or null for scalars and arrays.
+ */
+function recordValue(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    return value;
+}
+/**
+ * Rounds provider billed cost to the precision stored on AiRequest.
+ *
+ * @param value - USD cost before persistence rounding.
+ * @returns Cost rounded to eight decimal places.
+ */
+function roundCostUSD(value) {
+    return Math.round(value * USD_COST_PRECISION) / USD_COST_PRECISION;
+}

package/dist/ai/ResponsesProviderCall.d.ts

@@ -0,0 +1,13 @@
+import type { ResponsesProviderCallInput, ResponsesProviderCallResult } from './contracts/ResponsesProviderCall.js';
+export type { ResponsesProviderCallInput, ResponsesProviderCallResult } from './contracts/ResponsesProviderCall.js';
+/**
+ * Sends one Responses API request to an OpenAI-compatible provider.
+ *
+ * This is pure transport: it performs the HTTP call and parses the payload and
+ * headers. Tracking, rate limiting, failover policy, and error shaping stay in
+ * the AI service so every attempt in a failover chain shares one lifecycle.
+ *
+ * @param input - Provider connection, request payload, and fetch implementation.
+ * @returns Raw provider response for the caller to classify.
+ */
+export declare function sendResponsesRequest(input: ResponsesProviderCallInput): Promise<ResponsesProviderCallResult>;

package/dist/ai/ResponsesProviderCall.js

@@ -0,0 +1,29 @@
+import { providerResponseMetadata } from './AIRateLimiter.js';
+/**
+ * Sends one Responses API request to an OpenAI-compatible provider.
+ *
+ * This is pure transport: it performs the HTTP call and parses the payload and
+ * headers. Tracking, rate limiting, failover policy, and error shaping stay in
+ * the AI service so every attempt in a failover chain shares one lifecycle.
+ *
+ * @param input - Provider connection, request payload, and fetch implementation.
+ * @returns Raw provider response for the caller to classify.
+ */
+export async function sendResponsesRequest(input) {
+    const response = await input.fetcher(`${input.baseUrl}/responses`, {
+        method: 'POST',
+        headers: {
+            authorization: `Bearer ${input.apiKey}`,
+            'content-type': 'application/json',
+        },
+        body: JSON.stringify(input.request),
+    });
+    const metadata = providerResponseMetadata(response.headers);
+    const payload = await response.json().catch(() => null);
+    return {
+        ok: response.ok,
+        status: response.status,
+        payload,
+        metadata,
+    };
+}

package/dist/ai/agentCitations.d.ts

@@ -0,0 +1,27 @@
+import { type AgentCitation } from '@db3.ai/pure';
+/**
+ * Extracts a normalized URL citation from a Responses streaming annotation.
+ *
+ * @param record - Raw `response.output_text.annotation.added` event.
+ * @returns Valid URL citation, or null for unsupported annotations.
+ */
+export declare function agentCitationFromStreamRecord(record: Record<string, unknown>): AgentCitation | null;
+/**
+ * Extracts URL citations from the final Agents SDK model response.
+ *
+ * A null result means the provider did not expose an authoritative annotation
+ * collection, so callers may fall back to citations observed in stream events.
+ * An empty array is authoritative and means the final response had no citations.
+ *
+ * @param rawResponses - Agents SDK model responses generated by the run.
+ * @returns Final normalized citations, or null when annotations are unavailable.
+ */
+export declare function agentCitationsFromFinalModelResponse(rawResponses: unknown): AgentCitation[] | null;
+/**
+ * Adds a citation to an in-memory collection when its occurrence is new.
+ *
+ * @param citations - Mutable citations collected for the current attempt.
+ * @param citation - Citation occurrence to remember.
+ * @returns True when the citation was added.
+ */
+export declare function rememberAgentCitation(citations: AgentCitation[], citation: AgentCitation): boolean;

package/dist/ai/agentCitations.js

@@ -0,0 +1,153 @@
+import { agentCitationOccurrenceKey, normalizedAgentCitations } from '@db3.ai/pure';
+/**
+ * Extracts a normalized URL citation from a Responses streaming annotation.
+ *
+ * @param record - Raw `response.output_text.annotation.added` event.
+ * @returns Valid URL citation, or null for unsupported annotations.
+ */
+export function agentCitationFromStreamRecord(record) {
+    if (record.type !== 'response.output_text.annotation.added')
+        return null;
+    const annotation = recordValue(record.annotation);
+    const itemId = stringValue(record.item_id) || stringValue(record.itemId);
+    const annotationIndex = integerValue(record.annotation_index) ?? integerValue(record.annotationIndex);
+    const contentIndex = integerValue(record.content_index) ?? integerValue(record.contentIndex) ?? 0;
+    return providerUrlCitation(annotation, {
+        id: citationId(itemId, contentIndex, annotationIndex),
+        offset: contentIndex === 0 ? 0 : null,
+    });
+}
+/**
+ * Extracts URL citations from the final Agents SDK model response.
+ *
+ * A null result means the provider did not expose an authoritative annotation
+ * collection, so callers may fall back to citations observed in stream events.
+ * An empty array is authoritative and means the final response had no citations.
+ *
+ * @param rawResponses - Agents SDK model responses generated by the run.
+ * @returns Final normalized citations, or null when annotations are unavailable.
+ */
+export function agentCitationsFromFinalModelResponse(rawResponses) {
+    if (!Array.isArray(rawResponses) || rawResponses.length === 0)
+        return null;
+    const response = recordValue(rawResponses.at(-1));
+    const output = Array.isArray(response?.output) ? response.output : null;
+    if (!output || output.length === 0)
+        return null;
+    const message = recordValue(output.at(-1));
+    if (!message)
+        return null;
+    const content = message.type === 'message' && Array.isArray(message.content)
+        ? message.content
+        : null;
+    if (!content)
+        return null;
+    const messageId = stringValue(message.id);
+    const citations = [];
+    let textOffset = 0;
+    let hasAnnotationCollection = false;
+    for (let contentIndex = 0; contentIndex < content.length; contentIndex += 1) {
+        const part = recordValue(content[contentIndex]);
+        if (part?.type !== 'output_text')
+            continue;
+        const providerData = recordValue(part.providerData);
+        const annotations = Array.isArray(providerData?.annotations)
+            ? providerData.annotations
+            : Array.isArray(part.annotations)
+                ? part.annotations
+                : null;
+        if (annotations) {
+            hasAnnotationCollection = true;
+            for (let annotationIndex = 0; annotationIndex < annotations.length; annotationIndex += 1) {
+                const citation = providerUrlCitation(recordValue(annotations[annotationIndex]), {
+                    id: citationId(messageId, contentIndex, annotationIndex),
+                    offset: textOffset,
+                });
+                if (citation)
+                    citations.push(citation);
+            }
+        }
+        textOffset += stringValue(part.text)?.length ?? 0;
+    }
+    return hasAnnotationCollection ? normalizedAgentCitations(citations) : null;
+}
+/**
+ * Adds a citation to an in-memory collection when its occurrence is new.
+ *
+ * @param citations - Mutable citations collected for the current attempt.
+ * @param citation - Citation occurrence to remember.
+ * @returns True when the citation was added.
+ */
+export function rememberAgentCitation(citations, citation) {
+    const key = agentCitationOccurrenceKey(citation);
+    if (citations.some(existing => agentCitationOccurrenceKey(existing) === key))
+        return false;
+    citations.push(citation);
+    return true;
+}
+/**
+ * Converts a provider URL annotation into application's public citation contract.
+ *
+ * @param annotation - Raw provider annotation object.
+ * @param context - Stable id and complete-message character offset.
+ * @returns Valid normalized citation, or null when required data is absent.
+ */
+function providerUrlCitation(annotation, context) {
+    if (!annotation || annotation.type !== 'url_citation' || context.offset === null)
+        return null;
+    const startIndex = integerValue(annotation.start_index) ?? integerValue(annotation.startIndex);
+    const endIndex = integerValue(annotation.end_index) ?? integerValue(annotation.endIndex);
+    const title = stringValue(annotation.title)?.trim();
+    const url = stringValue(annotation.url)?.trim();
+    if (startIndex === null || endIndex === null || !title || !url)
+        return null;
+    const citations = normalizedAgentCitations([{
+            id: context.id,
+            type: 'url',
+            title,
+            url,
+            startIndex: context.offset + startIndex,
+            endIndex: context.offset + endIndex,
+        }]);
+    return citations[0] ?? null;
+}
+/**
+ * Builds a stable id for one provider citation occurrence.
+ *
+ * @param itemId - Provider output message id when available.
+ * @param contentIndex - Output-text part index within the message.
+ * @param annotationIndex - Annotation index within the output-text part.
+ * @returns Stable citation id for streaming and restored UI state.
+ */
+function citationId(itemId, contentIndex, annotationIndex) {
+    return `${itemId || 'output'}:${contentIndex}:${annotationIndex ?? 0}`;
+}
+/**
+ * Narrows an unknown JSON value to a non-array record.
+ *
+ * @param value - Unknown provider value.
+ * @returns Object record, or null for primitives and arrays.
+ */
+function recordValue(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+/**
+ * Reads a non-empty string from an unknown provider value.
+ *
+ * @param value - Unknown provider value.
+ * @returns String value, or null when absent.
+ */
+function stringValue(value) {
+    return typeof value === 'string' && value ? value : null;
+}
+/**
+ * Reads a non-negative integer from an unknown provider value.
+ *
+ * @param value - Unknown provider index value.
+ * @returns Non-negative integer, or null when invalid.
+ */
+function integerValue(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : null;
+}

package/dist/ai/contracts/AI.d.ts

@@ -0,0 +1,347 @@
+import type { TextResponsePayload } from '@db3.ai/pure';
+import type { ZodType } from 'zod';
+import type { AiConversation } from '../AiConversation.js';
+import type { AiRequest } from '../AiRequest.js';
+import type { AiRateLimitEndpoint } from '../AiRateLimitBucket.js';
+import type { AIRateLimiter } from '../AIRateLimiter.js';
+/**
+ * Provider identifiers stored with AI requests and conversation messages.
+ *
+ * Every provider must expose an OpenAI-compatible API. Keep these values stable
+ * because they are persisted in tracking tables and rate-limit bucket keys.
+ */
+export declare const AI_PROVIDER: {
+    readonly openai: "openai";
+    readonly openrouter: "openrouter";
+    readonly groq: "groq";
+    readonly xai: "xai";
+    readonly deepseek: "deepseek";
+};
+/**
+ * Supported AI provider id.
+ */
+export type AIProvider = typeof AI_PROVIDER[keyof typeof AI_PROVIDER];
+/**
+ * Application-owned AI model configuration.
+ *
+ * `model` is the global fallback. Additional keys are stable runtime names,
+ * such as concrete agent class names, resolved through `AI.config(...)`.
+ */
+export interface AIConfig {
+    /** Global model used when a call or agent does not select its own model. */
+    model: string;
+    /** Named model override or the required global model. */
+    [name: string]: string;
+}
+/**
+ * Ordered provider selection for a call, an agent, or the app default.
+ *
+ * A single provider keeps normal single-provider behavior. An ordered list
+ * fails over to the next provider using each provider's default model. An
+ * ordered record pins a model per provider and preserves insertion order:
+ *
+ * ```ts
+ * provider: [AI_PROVIDER.openai, AI_PROVIDER.openrouter]
+ * provider: {
+ * 	[AI_PROVIDER.openai]: 'gpt-5.4-mini',
+ * 	[AI_PROVIDER.openrouter]: 'comparable-mini-model',
+ * }
+ * ```
+ */
+export type AIProviderSelection = AIProvider | AIProvider[] | Partial<Record<AIProvider, string>>;
+/** Explicit application credit charge attached to one AI provider operation. */
+export interface AIUsageCharge {
+    /** Independent credit bucket selected by the feature starting the operation. */
+    bucket: string;
+    /** Positive whole-credit amount consumed before provider work begins. */
+    credits: number;
+    /**
+     * Optional caller-owned key for one logical usage charge.
+     *
+     * Supply this when queue retries or other re-executions can create more than
+     * one tracked AI request for the same billable operation. When omitted, the
+     * allowance adapter derives its key from the tracked AI request.
+     */
+    idempotencyKey?: string;
+}
+/**
+ * Context passed to an application-owned customer allowance hook.
+ *
+ * This hook is separate from provider rate limits. Provider limits answer "can
+ * this API key call OpenAI right now"; allowance checks answer "is this user,
+ * scope, team, or customer allowed to spend more application AI budget".
+ */
+export interface AIAllowanceCheckInput {
+    /** Provider that will receive the request. */
+    provider: AIProvider;
+    /** Provider endpoint family, such as responses or embeddings. */
+    endpoint: AiRateLimitEndpoint;
+    /** Provider model or shared limit key used by the request. */
+    model: string;
+    /** Logical app operation, such as responses.create or agents.run.stream. */
+    operation: string;
+    /** User record or id associated with this request. */
+    user?: AIRecordIdentity | string | null;
+    /** Scope record or id associated with this request. */
+    scope?: AIRecordIdentity | string | null;
+    /** Pending tracked request row, when one has already been created. */
+    aiRequest?: AiRequest | null;
+    /** Estimated token cost used for pre-flight decisions. */
+    estimatedTokens?: number | null;
+    /** Explicit app credit charge, or null for unmetered and separately funded work. */
+    usage?: AIUsageCharge | null;
+    /** Extra operation metadata for policy decisions and audit messages. */
+    metadata?: Record<string, unknown> | null;
+}
+/**
+ * Application-defined allowance checker.
+ *
+ * Throw an app-level error from this hook to stop a request before provider
+ * capacity is reserved or external work starts.
+ */
+export type AIAllowanceChecker = (input: AIAllowanceCheckInput) => void | Promise<void>;
+/**
+ * Runtime configuration for the AI service.
+ *
+ * Values supplied here override environment variables, which makes the service
+ * easy to test with a fake fetch implementation or alternate API endpoint.
+ */
+export interface AIOptions {
+    /** Maximum duration of each provider HTTP request, including SDK model turns. */
+    timeoutMs?: number;
+    /** Persisted logical scope field. Apps may map this to an existing domain field. */
+    scopeField?: string;
+    /** Model subclasses registered by the application migration workflow. */
+    models?: Partial<AIModels>;
+    /** OpenAI API key. Falls back to OPENAI_API_KEY when omitted. */
+    apiKey?: string;
+    /** Base API URL without the /responses suffix. Falls back to OPENAI_BASE_URL. */
+    baseUrl?: string;
+    /** Model name to use instead of the application config default. */
+    model?: string;
+    /** Default provider failover chain. Falls back to AI_PROVIDER_CHAIN, then OpenAI only. */
+    provider?: AIProviderSelection;
+    /** Fetch implementation used to send requests. Defaults to global fetch. */
+    fetch?: typeof fetch;
+    /** Rate limiter used before provider requests. Pass false only in isolated tests. */
+    rateLimiter?: AIRateLimiter | false;
+    /** Optional customer allowance hook. Defaults to no-op until billing limits exist. */
+    allowance?: AIAllowanceChecker | false;
+}
+/**
+ * Plain text request sent to the Responses API.
+ */
+export interface GenerateTextInput {
+    /** Optional per-call model override for the OpenAI provider entry. */
+    model?: string;
+    /** Optional provider failover chain overriding the app default for this call. */
+    provider?: AIProviderSelection;
+    /** System-level instructions that define the assistant's task and constraints. */
+    instructions: string;
+    /** User-level prompt or context for the request. */
+    input: string;
+    /** Optional maximum response tokens sent as max_output_tokens. */
+    maxOutputTokens?: number;
+}
+/**
+ * Text generation result with optional database tracking identifiers.
+ */
+export interface GenerateTextResult {
+    /** Extracted assistant text from the Responses API payload. */
+    text: string;
+    /** Saved AiRequest id when response logging is enabled; otherwise null. */
+    aiRequestId: string | null;
+    /** Saved response id. Currently mirrors aiRequestId because responses live on AiRequest. */
+    aiResponseId: string | null;
+    /** Conversation id used for tracked request and message rows; otherwise null. */
+    conversationId: string | null;
+}
+/**
+ * Embedding generation result with optional database tracking identifier.
+ */
+export interface GenerateEmbeddingResult {
+    /** Embedding vector returned by the provider. */
+    vector: number[];
+    /** Embedding model used for the request. */
+    model: string;
+    /** Saved AiRequest id when response logging is enabled; otherwise null. */
+    aiRequestId: string | null;
+}
+/**
+ * Structured generation request that asks the provider to return JSON matching
+ * a Zod schema and validates the parsed result before returning it.
+ */
+export interface GenerateStructuredInput<TValue> extends GenerateTextInput {
+    /** Schema used both for provider response formatting and local validation. */
+    schema: ZodType<TValue>;
+    /** Stable schema name sent to OpenAI and stored in request metadata. */
+    schemaName: string;
+}
+/**
+ * Optional metadata that controls how AI requests are attached to application
+ * records when response logging is enabled.
+ */
+export interface AIResponseLogOptions extends Record<string, unknown> {
+    /** User record or id to associate with the request. Defaults to the active user. */
+    user?: AIRecordIdentity | string | null;
+    /** Scope record or id to associate with the request. */
+    scope?: AIRecordIdentity | string | null;
+    /** Existing conversation record or id to append to. Creates a new conversation when omitted. */
+    conversation?: AiConversation | string | null;
+    /** Immediate parent AI request that caused this nested provider request. */
+    parentAiRequest?: AiRequest | string | null;
+    /** Logical feature or agent name shown on the conversation/request. */
+    agent?: string | null;
+    /** Human-readable conversation title when a new conversation is created. */
+    title?: string | null;
+    /** Extra JSON metadata copied to the conversation, request, and message rows. */
+    metadata?: Record<string, unknown> | null;
+    /** Explicit app credit charge checked before provider work begins. */
+    usage?: AIUsageCharge | null;
+    /** Set to false to opt out of saving request, response, and message rows. */
+    saveAiResponse?: boolean;
+}
+/** Untrusted provider text response, including optional token usage. */
+export interface TextResponsePayloadWithUsage extends TextResponsePayload {
+    /** Provider completion status; omitted by some compatible endpoints. */
+    status?: unknown;
+    usage?: unknown;
+}
+/** Untrusted embedding response validated by the AI service before it is returned. */
+export interface EmbeddingResponsePayloadWithUsage {
+    data?: Array<{
+        embedding?: unknown;
+        index?: unknown;
+        object?: unknown;
+    }>;
+    model?: unknown;
+    object?: unknown;
+    usage?: unknown;
+    error?: unknown;
+}
+/**
+ * Image generation request sent to the provider Images API.
+ */
+export interface GenerateImageInput {
+    /** Optional per-call model override. Defaults to the `ImageGeneration` AI config entry. */
+    model?: string;
+    /** Detailed image prompt. */
+    prompt: string;
+    /** Provider image size, such as 1024x1024 or 1536x1024. */
+    size?: string;
+    /** Provider image quality, such as low, medium, high, or auto. */
+    quality?: string;
+    /** Provider image output format. Defaults to png. */
+    outputFormat?: 'png' | 'jpeg' | 'webp';
+    /** Provider end-user id forwarded to OpenAI, when available. */
+    user?: string | null;
+}
+/**
+ * Provider Images API response shape used by the AI service.
+ */
+export interface ImageResponsePayloadWithUsage {
+    created?: unknown;
+    data?: Array<{
+        b64_json?: unknown;
+        revised_prompt?: unknown;
+        url?: unknown;
+    }>;
+    error?: unknown;
+    usage?: unknown;
+}
+/**
+ * Image bytes and tracking context passed to a storage callback.
+ */
+export interface GenerateImageStoreInput {
+    /** Base64-encoded image bytes returned by the provider. */
+    b64Json: string;
+    /** Tracked request row, when request logging is enabled. */
+    aiRequest: AiRequest | null;
+    /** Tracked request id, when request logging is enabled. */
+    aiRequestId: string | null;
+    /** Provider model used for this image. */
+    model: string;
+    /** Prompt sent to the provider. */
+    prompt: string;
+    /** Image size sent to the provider. */
+    size: string | null;
+    /** Image quality sent to the provider. */
+    quality: string | null;
+    /** Image output format sent to the provider. */
+    outputFormat: string;
+    /** Compact provider response without raw image bytes. */
+    providerResponse: Record<string, unknown> | null;
+}
+/**
+ * Stores generated image bytes and returns the app-owned storage reference.
+ */
+export type GenerateImageStoreCallback<TStored> = (input: GenerateImageStoreInput) => TStored | Promise<TStored>;
+/**
+ * Optional metadata and storage callback for image generation.
+ */
+export interface GenerateImageOptions<TStored = unknown> extends RequestLogOptions {
+    /** Saves generated image bytes and returns the value stored on AiRequest.response. */
+    store?: GenerateImageStoreCallback<TStored>;
+}
+/**
+ * Image generation result with optional storage and tracking identifiers.
+ */
+export interface GenerateImageResult<TStored = unknown> {
+    /** Base64-encoded image bytes returned by the provider. */
+    b64Json: string;
+    /** Image model used for the request. */
+    model: string;
+    /** Saved AiRequest id when response logging is enabled; otherwise null. */
+    aiRequestId: string | null;
+    /** App-owned storage reference returned by the storage callback. */
+    stored: TStored | null;
+}
+/** Tracking metadata and an optional application-specific operation name. */
+export interface RequestLogOptions extends AIResponseLogOptions {
+    operation?: string;
+}
+/** Internal lifecycle state for a persisted text request and its current attempt. */
+export interface TrackedRequest {
+    aiRequest: AiRequest;
+    conversation: AiConversation;
+    nextSequence: number;
+    startTimeMs: number;
+    userId: string | null;
+    scopeId: string | null;
+    /** Model for the current provider attempt; updated when failover switches providers. */
+    model: string;
+    /** Provider for the current attempt; updated when failover switches providers. */
+    provider: AIProvider;
+}
+/** Internal lifecycle state for a persisted embedding operation. */
+export interface TrackedEmbeddingRequest {
+    aiRequest: AiRequest;
+    startTimeMs: number;
+    model: string;
+}
+/** Internal lifecycle state for a persisted image operation. */
+export interface TrackedImageRequest {
+    aiRequest: AiRequest;
+    startTimeMs: number;
+    model: string;
+}
+/** Normalized provider token counts; null means the provider did not report a value. */
+export interface TokenUsage {
+    inputTokens: number | null;
+    outputTokens: number | null;
+    totalTokens: number | null;
+    reasoningTokens: number | null;
+    cachedTokens: number | null;
+    /** Input tokens written into a billable provider prompt cache. */
+    cacheWriteTokens: number | null;
+}
+/** Minimal identity accepted at a framework ownership boundary. */
+export interface AIRecordIdentity {
+    id: unknown;
+}
+/** Model constructors used for every AI persistence operation. */
+export interface AIModels {
+    conversation: typeof AiConversation;
+    request: typeof AiRequest;
+    message: typeof import('../AiMessage.js').AiMessage;
+}