@db3.ai/app 0.1.0-beta.1

package/dist/ai/Models.js

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

package/dist/ai/OpenAIProviderError.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Normalized OpenAI provider failure fields used by application retry policy.
+ */
+export interface OpenAIProviderErrorDetails {
+    /** Provider error code, when supplied by the SDK or response payload. */
+    code: string | null;
+    /** HTTP status, when the provider rejected the request before streaming began. */
+    status: number | null;
+    /** Provider request identifier used for support and diagnostics. */
+    requestId: string | null;
+    /** Human-readable provider failure message. */
+    message: string;
+}
+/**
+ * Extracts stable OpenAI failure fields from SDK errors or response payloads.
+ *
+ * Streaming Responses failures can carry no HTTP status while still exposing a
+ * provider `code`, so callers must not classify them from status alone.
+ *
+ * @param value - Unknown SDK error or provider response payload.
+ * @returns Normalized provider failure details.
+ */
+export declare function openAIProviderError(value: unknown): OpenAIProviderErrorDetails;
+/**
+ * Checks whether an OpenAI failure represents exhausted account or project quota.
+ *
+ * @param value - Unknown SDK error or provider response payload.
+ * @returns True when the provider error code requires credits or billing changes.
+ */
+export declare function isOpenAIQuotaError(value: unknown): boolean;

package/dist/ai/OpenAIProviderError.js

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

package/dist/ai/OpenAIQuotaRetry.d.ts

@@ -0,0 +1,27 @@
+import type { OpenAIQuotaRetryMetadata, OpenAIQuotaRetryDecision } from './contracts/QuotaRetry.js';
+export type { OpenAIQuotaRetryMetadata, OpenAIQuotaRetryDecision } from './contracts/QuotaRetry.js';
+import type { AiRequest } from './AiRequest.js';
+/**
+ * Builds a bounded exponential retry decision for an OpenAI quota failure.
+ *
+ * @param error - Unknown provider error thrown by the Agents SDK.
+ * @param request - Persisted AI request carrying previous quota retry metadata.
+ * @param now - Current time used for deterministic scheduling.
+ * @returns Quota retry decision, or null for another failure category.
+ */
+export declare function openAIQuotaRetryDecision(error: unknown, request: AiRequest, now?: Date): OpenAIQuotaRetryDecision | null;
+/**
+ * Merges quota retry state into existing AI request metadata.
+ *
+ * @param metadata - Existing request metadata.
+ * @param quotaRetry - Quota retry state to persist.
+ * @returns Request metadata containing the latest retry schedule.
+ */
+export declare function withOpenAIQuotaRetryMetadata(metadata: Record<string, unknown> | null, quotaRetry: OpenAIQuotaRetryMetadata): Record<string, unknown>;
+/**
+ * Removes completed quota retry state from AI request metadata.
+ *
+ * @param metadata - Existing request metadata.
+ * @returns Metadata without the internal quota retry entry.
+ */
+export declare function withoutOpenAIQuotaRetryMetadata(metadata: Record<string, unknown> | null): Record<string, unknown>;

package/dist/ai/OpenAIQuotaRetry.js

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

package/dist/ai/ProviderCosts.d.ts

@@ -0,0 +1,55 @@
+import { type AIProvider } from './contracts/AI.js';
+/** Provider response field used as the authoritative billed-cost source. */
+export type ProviderReportedCostSource = 'openrouter_usage_cost' | 'xai_usage_cost_in_usd_ticks';
+/** Authoritative billed cost reported for one provider request. */
+export interface ProviderReportedCost {
+    /** Provider response id used to deduplicate repeated terminal stream events. */
+    responseId: string;
+    /** Billed request cost in USD, rounded to the application's stored precision. */
+    costUSD: number;
+    /** Provider response field from which the cost was derived. */
+    source: ProviderReportedCostSource;
+}
+/** Completeness summary for provider-reported costs across one agent attempt. */
+export interface ProviderReportedCostSummary {
+    /** Safely known subtotal across every captured provider response. */
+    knownCostUSD: number;
+    /** Complete attempt cost, or null when any expected response lacks billed cost. */
+    costUSD: number | null;
+    /** Number of unique provider responses with an authoritative billed cost. */
+    reportedRequestCount: number;
+    /** Number of provider requests reported by the Agents SDK. */
+    expectedRequestCount: number;
+    /** Provider fields that supplied the captured costs. */
+    sources: ProviderReportedCostSource[];
+}
+/**
+ * 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 declare function providerReportedCostUSD(provider: AIProvider | string | null, payload: unknown): number | 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 declare function providerReportedCost(provider: AIProvider | string | null, payload: unknown, responseId: unknown): ProviderReportedCost | null;
+/**
+ * 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 declare function summarizeProviderReportedCosts(costs: Map<string, ProviderReportedCost>, expectedRequestCount: number): ProviderReportedCostSummary;