@opengeni/core 3.0.1 → 3.1.2

package/src/billing/model-usage-settlement.ts

@@ -0,0 +1,472 @@
+import {
+  calculateGatewayReportedCostBreakdown,
+  calculateGatewayReportedProviderCostMicros,
+  calculateModelListUsageCostSnapshot,
+  calculateModelUsageCostBreakdown,
+  canonicalizeConfiguredModelId,
+  configuredModelListPricingSchedules,
+  configuredModelPricingSchedules,
+  resolveModelProvider,
+  OPENGENI_GATEWAY_PROVIDER_ID,
+  OPPER_PROVIDER_ID,
+  ORGANIZATION_OPPER_PROVIDER_ID,
+  WORKSPACE_GATEWAY_PROVIDER_ID,
+  WORKSPACE_OPPER_PROVIDER_ID,
+  type Settings,
+} from "@opengeni/config";
+import { createHash } from "node:crypto";
+import type { LatencyMode } from "@opengeni/contracts";
+import type { InsightsUsageClassMicros } from "@opengeni/contracts/insights-usage";
+import {
+  applyCreditDebitUpToBalance,
+  isStoredVerbatimAsLosslessJsonString,
+  recordUsageEvent,
+  settleSessionUsageReceipt,
+  toPostgresLosslessJson,
+  type Database,
+} from "@opengeni/db";
+import type { ModelCallUsageNormalization, ModelResponseUsage } from "@opengeni/runtime";
+import type { ModelUsageInput } from "@opengeni/config";
+import {
+  recordSessionUsageLimitEvent,
+  type SessionUsageLimitMetricsSink,
+} from "../session-usage-limit-metrics";
+
+/**
+ * Price and settle one authoritative model response: the token-cap usage
+ * event, the `model.cost` event, and (for Opengeni-credit models) the
+ * idempotent credit debit. Agent turns and stateless single model calls both
+ * settle here; `sourceId` is the durable identity every idempotency key
+ * derives from, so a retried settlement never charges twice.
+ */
+
+export type ModelUsageBillingRecord = {
+  billingPath: "opengeni_credits" | "external";
+  /** Same quantity written to usage_events.model.cost when present; else 0. */
+  pricedCostMicros: number;
+  /** Hypothetical provider-rate USD micros; never an Opengeni charge. */
+  estimatedProviderCostMicros: number | null;
+  /** Hypothetical Opengeni credit price at the captured rate; never a debit. */
+  equivalentCreditCostMicros: number | null;
+  pricingSource: "configured_list_price" | "gateway_reported" | null;
+  /** Forward-only provider list class snapshot; older facts/events stay unknown. */
+  listByClassMicros?: InsightsUsageClassMicros | null;
+  listByClassApprox?: boolean;
+  normalizedUsage: ModelCallUsageNormalization;
+  upstreamProvider?: string;
+};
+
+// Exported for unit testing the external-billing bypass; not part of the activity surface.
+
+export type ModelUsageSettlementInput = {
+  accountId: string;
+  workspaceId: string;
+  /** Product model id used for pricing and ledger attribution. */
+  model: string;
+  chargesOpenGeniCredits: boolean;
+  countsTowardTokenCap: boolean;
+  creditPolicyRevision?: number | undefined;
+  gatewayBilling?: ModelResponseUsage["gatewayBilling"];
+  normalizedUsage: ModelCallUsageNormalization;
+  /** Durable source identity (for a turn, `${turnId}:${sourceKey}`). */
+  sourceId: string;
+  sessionId?: string | null;
+  /**
+   * The session whose task usage limit this response counts against when it
+   * differs from the usage attribution `sessionId` (an attempt-authenticated
+   * single-model call keeps its existing usage attribution). Defaults to
+   * `sessionId`.
+   */
+  usageLimitSessionId?: string | null;
+  turnId?: string | null;
+  turnAttemptId?: string | null;
+  latencyMode?: LatencyMode;
+  /** Non-secret correlation fields added to the credit debit metadata. */
+  debitMetadata?: Record<string, unknown>;
+  /** Best-effort metrics hook after a committed debit. */
+  onCreditsDebited?: (result: { debitedMicros: number; grantDebitedMicros: number }) => void;
+  /** Content-free per-task usage limit diagnostics (closed-set labels only). */
+  usageLimitMetrics?: SessionUsageLimitMetricsSink | null;
+  /**
+   * Attempt-scoped custody for a receipt whose write failed. When present, a
+   * failed receipt write is handed over (content-free, original identity) and
+   * settlement continues, so the response is never lost or replayed; the
+   * owner must write held receipts before its next model request. Without
+   * custody the failure throws.
+   */
+  receiptCustody?: ((receipt: HeldSessionUsageReceipt, error: unknown) => void) | null;
+};
+
+/** A content-free task usage receipt whose write is still owed. */
+export type HeldSessionUsageReceipt = {
+  sessionId: string;
+  sourceId: string;
+  turnId: string | null;
+  amountMicros: number | null;
+  pricingSource: "configured_list_price" | "gateway_reported" | null;
+  model: string | null;
+};
+
+/**
+ * The per-task meter amount: the canonical pre-margin estimate, but only when
+ * the response actually reported usage. A response without token telemetry
+ * (or with zero input and output tokens) and no provider-reported cost is an
+ * unknown amount, never a known-free call. Billing and Insights keep their
+ * own `estimatedProviderCostMicros` unchanged.
+ */
+export function sessionUsageMeterAmountMicros(input: {
+  estimatedProviderCostMicros: number | null;
+  gatewayReported: boolean;
+  inputTokens: number | null;
+  outputTokens: number | null;
+}): number | null {
+  if (input.estimatedProviderCostMicros === null) return null;
+  if (input.gatewayReported) return input.estimatedProviderCostMicros;
+  return (input.inputTokens ?? 0) + (input.outputTokens ?? 0) > 0
+    ? input.estimatedProviderCostMicros
+    : null;
+}
+
+/** The receipt table's `source_id` byte bound. */
+export const SESSION_USAGE_RECEIPT_SOURCE_ID_MAX_BYTES = 1100;
+
+/**
+ * The per-task receipt identity for a producer source. Every identity the
+ * event trigger or the legacy import can produce (`<turnId>:<sourceKey>` with
+ * a source key of at most 1024 bytes) fits the bound and is used unchanged,
+ * so their deduplication is untouched. Only a longer identity, which those
+ * paths skip, is replaced by a stable digest, so a long provider response id
+ * is recorded once instead of failing the receipt write on every retry.
+ *
+ * A source key PostgreSQL cannot store as given (NUL, a lone UTF-16
+ * surrogate, the lossless codec's own prefix) is stored by the event in its
+ * lossless encoding, and the trigger meters that encoded key. The receipt uses
+ * the same encoded key, so both writers share one identity instead of the
+ * direct write being refused.
+ */
+export function sessionUsageReceiptSourceId(sourceId: string, turnId?: string | null): string {
+  const turnPrefix = turnId && sourceId.startsWith(`${turnId}:`) ? `${turnId}:` : "";
+  const sourceKey = sourceId.slice(turnPrefix.length);
+  const stored = isStoredVerbatimAsLosslessJsonString(sourceKey)
+    ? sourceId
+    : `${turnPrefix}${toPostgresLosslessJson(sourceKey) as string}`;
+  if (Buffer.byteLength(stored, "utf8") <= SESSION_USAGE_RECEIPT_SOURCE_ID_MAX_BYTES) {
+    return stored;
+  }
+  return `sha256:${createHash("sha256").update(stored, "utf8").digest("hex")}`;
+}
+
+export async function settleModelUsage(
+  settings: Settings,
+  db: Database,
+  input: ModelUsageSettlementInput,
+): Promise<ModelUsageBillingRecord> {
+  const normalizedUsage = input.normalizedUsage;
+  const usageContext = {
+    ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+    ...(input.turnId ? { turnId: input.turnId } : {}),
+    ...(input.turnAttemptId ? { turnAttemptId: input.turnAttemptId } : {}),
+  };
+  const sanitizedUsage = sanitizedModelUsageInput(normalizedUsage);
+  const inputTokens = sanitizedUsage.inputTokens ?? 0;
+  const outputTokens = sanitizedUsage.outputTokens ?? 0;
+  const totalTokens = sanitizedUsage.totalTokens ?? 0;
+  const { chargesOpenGeniCredits, countsTowardTokenCap } = input;
+  const resolvedGatewayModel = input.gatewayBilling
+    ? resolveModelProvider(settings, input.model)
+    : undefined;
+  const gatewayProviderId = resolvedGatewayModel?.provider.id;
+  // Opper reports the exact USD cost of every response (`usage.opper.cost`);
+  // the Chat adapter surfaces it with `finalProvider: "opper"`.
+  const opperReported =
+    (gatewayProviderId === OPPER_PROVIDER_ID ||
+      gatewayProviderId === WORKSPACE_OPPER_PROVIDER_ID ||
+      gatewayProviderId === ORGANIZATION_OPPER_PROVIDER_ID) &&
+    input.gatewayBilling?.finalProvider === "opper";
+  const gatewayBilling =
+    gatewayProviderId === OPENGENI_GATEWAY_PROVIDER_ID ||
+    gatewayProviderId === WORKSPACE_GATEWAY_PROVIDER_ID ||
+    opperReported
+      ? input.gatewayBilling
+      : undefined;
+  const allowedProviders = resolvedGatewayModel?.model.requestPolicy?.gateway.only;
+  // Scoped Opper rails settle externally; record the exact provider cost only.
+  const unpinnedWorkspaceGatewayModel =
+    (gatewayProviderId === WORKSPACE_GATEWAY_PROVIDER_ID && allowedProviders === undefined) ||
+    (opperReported && gatewayProviderId !== OPPER_PROVIDER_ID);
+  if (gatewayBilling && !opperReported) {
+    if (
+      !unpinnedWorkspaceGatewayModel &&
+      (!allowedProviders ||
+        !(allowedProviders as readonly string[]).includes(gatewayBilling.finalProvider))
+    ) {
+      throw new Error(
+        `AI Gateway reported unapproved provider ${gatewayBilling.finalProvider} for ${input.model}`,
+      );
+    }
+    if (unpinnedWorkspaceGatewayModel && chargesOpenGeniCredits) {
+      throw new Error(
+        `Workspace Gateway custom model ${input.model} cannot charge Opengeni credits without pinned pricing`,
+      );
+    }
+  }
+  const pricingSchedules = configuredModelPricingSchedules(settings);
+  const configuredPricingModel = pricingSchedules[input.model]
+    ? input.model
+    : input.model.startsWith("codex/") && pricingSchedules[input.model.slice("codex/".length)]
+      ? input.model.slice("codex/".length)
+      : null;
+  const pricingBreakdown = gatewayBilling
+    ? unpinnedWorkspaceGatewayModel
+      ? {
+          providerCostMicros: calculateGatewayReportedProviderCostMicros(
+            gatewayBilling.inferenceCostUsd,
+          ),
+          creditCostMicros: 0,
+        }
+      : calculateGatewayReportedCostBreakdown(
+          settings,
+          configuredPricingModel ?? input.model,
+          gatewayBilling.inferenceCostUsd,
+          { inputTokens },
+        )
+    : configuredPricingModel
+      ? calculateModelUsageCostBreakdown(settings, configuredPricingModel, sanitizedUsage, {
+          latencyMode: input.latencyMode ?? "standard",
+        })
+      : null;
+  const hasCompleteCoreTokenTelemetry =
+    normalizedUsage.telemetry.inputTokens !== null &&
+    normalizedUsage.telemetry.outputTokens !== null;
+  // Comparison rates are deliberately separate from debit authority. The
+  // current usage frame does not establish geography/service-tier provenance,
+  // so forward class splits stay unknown even when a total estimate is priced.
+  const listPricingSchedules = configuredModelListPricingSchedules(settings);
+  const configuredListPricingModel = listPricingSchedules[input.model]
+    ? input.model
+    : input.model.startsWith("codex/") && listPricingSchedules[input.model.slice("codex/".length)]
+      ? input.model.slice("codex/".length)
+      : null;
+  const listSnapshot =
+    !gatewayBilling && hasCompleteCoreTokenTelemetry && configuredListPricingModel
+      ? calculateModelListUsageCostSnapshot(settings, configuredListPricingModel, sanitizedUsage, {
+          latencyMode: input.latencyMode ?? "standard",
+          priceContextKnown: false,
+        })
+      : null;
+  const listClasses = {
+    listByClassMicros: listSnapshot?.listByClassMicros ?? null,
+    listByClassApprox: listSnapshot?.listByClassApprox ?? false,
+  };
+  const estimatedProviderCostMicros = gatewayBilling
+    ? (pricingBreakdown?.providerCostMicros ?? null)
+    : hasCompleteCoreTokenTelemetry
+      ? (listSnapshot?.providerCostMicros ?? pricingBreakdown?.providerCostMicros ?? null)
+      : null;
+  const equivalentCreditCostMicros =
+    pricingBreakdown && !unpinnedWorkspaceGatewayModel
+      ? gatewayBilling || hasCompleteCoreTokenTelemetry
+        ? pricingBreakdown.creditCostMicros
+        : null
+      : null;
+  const pricingSource = gatewayBilling
+    ? ("gateway_reported" as const)
+    : estimatedProviderCostMicros !== null
+      ? ("configured_list_price" as const)
+      : null;
+  // Per-task usage limit meter. Synchronous and awaited before any
+  // credit/usage write: the canonical pre-margin estimate is recorded once
+  // per source identity against the session's task root, for every funding
+  // path. A failed write is handed to the caller's custody (which must write
+  // it before any further model request) or, without custody, throws; the
+  // provider call is never replayed.
+  const usageLimitSessionId = input.usageLimitSessionId ?? input.sessionId;
+  if (usageLimitSessionId) {
+    const meterAmountMicros = sessionUsageMeterAmountMicros({
+      estimatedProviderCostMicros,
+      gatewayReported: pricingSource === "gateway_reported",
+      inputTokens: normalizedUsage.telemetry.inputTokens,
+      outputTokens: normalizedUsage.telemetry.outputTokens,
+    });
+    const held: HeldSessionUsageReceipt = {
+      sessionId: usageLimitSessionId,
+      sourceId: sessionUsageReceiptSourceId(input.sourceId, input.turnId),
+      turnId: input.turnId ?? null,
+      amountMicros: meterAmountMicros,
+      pricingSource: meterAmountMicros === null ? null : pricingSource,
+      model: input.model,
+    };
+    let receipt: Awaited<ReturnType<typeof settleSessionUsageReceipt>> | null = null;
+    try {
+      receipt = await settleSessionUsageReceipt(db, {
+        accountId: input.accountId,
+        workspaceId: input.workspaceId,
+        ...held,
+      });
+    } catch (error) {
+      if (!input.receiptCustody) {
+        recordSessionUsageLimitEvent(input.usageLimitMetrics, "settlement", "accounting_failure");
+        throw error;
+      }
+      input.receiptCustody(held, error);
+      recordSessionUsageLimitEvent(input.usageLimitMetrics, "settlement", "held");
+    }
+    if (receipt) {
+      recordSessionUsageLimitEvent(
+        input.usageLimitMetrics,
+        "settlement",
+        receipt.outcome === "conflict"
+          ? "source_conflict"
+          : meterAmountMicros === null && receipt.outcome === "recorded"
+            ? "unpriced"
+            : receipt.outcome,
+      );
+    }
+  }
+  // Provider settlement and workspace-facing cost are separate. Externally
+  // metered subscription/workspace turns remain exempt from the Opengeni token
+  // cap, while a deployment-funded free model still records model.tokens. Every
+  // non-credit path records a zero-cost marker and never consults pricing for a
+  // debit.
+  if (countsTowardTokenCap && totalTokens > 0) {
+    await recordUsageEvent(db, {
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      eventType: "model.tokens",
+      quantity: totalTokens,
+      unit: "tokens",
+      sourceResourceType: "model_response",
+      sourceResourceId: input.sourceId,
+      ...usageContext,
+      idempotencyKey: `usage:model.tokens:${input.sourceId}`,
+    });
+  }
+  if (!chargesOpenGeniCredits) {
+    await recordUsageEvent(db, {
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      eventType: "model.cost",
+      quantity: 0,
+      unit: "usd_micros",
+      sourceResourceType: "model_response",
+      sourceResourceId: input.sourceId,
+      ...usageContext,
+      idempotencyKey: `usage:model.cost:${input.sourceId}`,
+    });
+    return {
+      billingPath: "external",
+      pricedCostMicros: 0,
+      estimatedProviderCostMicros,
+      equivalentCreditCostMicros,
+      pricingSource,
+      ...listClasses,
+      normalizedUsage,
+      ...(gatewayBilling ? { upstreamProvider: gatewayBilling.finalProvider } : {}),
+    };
+  }
+  const shouldDebit = settings.billingMode === "stripe" || settings.usageLimitsMode === "managed";
+  if (!shouldDebit || (totalTokens === 0 && !gatewayBilling)) {
+    return {
+      billingPath: "opengeni_credits",
+      pricedCostMicros: 0,
+      estimatedProviderCostMicros,
+      equivalentCreditCostMicros,
+      pricingSource,
+      ...listClasses,
+      normalizedUsage,
+      ...(gatewayBilling ? { upstreamProvider: gatewayBilling.finalProvider } : {}),
+    };
+  }
+  if (!pricingBreakdown) {
+    throw new Error(`Missing model pricing for ${input.model}`);
+  }
+  const costMicros = pricingBreakdown.creditCostMicros;
+  await recordUsageEvent(db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    eventType: "model.cost",
+    quantity: costMicros,
+    unit: "usd_micros",
+    sourceResourceType: "model_response",
+    sourceResourceId: input.sourceId,
+    ...usageContext,
+    idempotencyKey: `usage:model.cost:${input.sourceId}`,
+  });
+  if (costMicros > 0) {
+    const result = await applyCreditDebitUpToBalance(db, {
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      type: "model_usage_debit",
+      requestedAmountMicros: costMicros,
+      modelId: canonicalizeConfiguredModelId(settings, input.model),
+      creditPolicyRevision: input.creditPolicyRevision,
+      sourceType: "model_response",
+      sourceId: input.sourceId,
+      idempotencyKey: `credit:model_usage_debit:${input.sourceId}`,
+      metadata: {
+        model: input.model,
+        ...input.debitMetadata,
+        latencyMode: input.latencyMode ?? "standard",
+        inputTokens,
+        outputTokens,
+        totalTokens,
+        // Additive: the prompt-cache slice of this call's input tokens, so the
+        // per-call debit record carries cache efficiency alongside the token
+        // counts. 0 when the provider did not report cached tokens.
+        cachedTokens: normalizedUsage.telemetry.cachedTokens ?? 0,
+        ...(gatewayBilling ? { gatewayProvider: gatewayBilling.finalProvider } : {}),
+      },
+    });
+    try {
+      input.onCreditsDebited?.(result);
+    } catch {
+      // The debit is committed; metrics are best-effort only.
+    }
+  }
+  return {
+    billingPath: "opengeni_credits",
+    pricedCostMicros: costMicros,
+    estimatedProviderCostMicros,
+    equivalentCreditCostMicros,
+    pricingSource,
+    ...listClasses,
+    normalizedUsage,
+    ...(gatewayBilling ? { upstreamProvider: gatewayBilling.finalProvider } : {}),
+  };
+}
+
+/** Bounded, validated token counts for pricing; raw provider values never price. */
+export function sanitizedModelUsageInput(normalized: ModelCallUsageNormalization): ModelUsageInput {
+  return {
+    ...(normalized.telemetry.inputTokens !== null
+      ? { inputTokens: normalized.telemetry.inputTokens }
+      : {}),
+    ...(normalized.telemetry.outputTokens !== null
+      ? { outputTokens: normalized.telemetry.outputTokens }
+      : {}),
+    ...(normalized.totalTokens !== null ? { totalTokens: normalized.totalTokens } : {}),
+    ...(normalized.telemetry.cachedTokens !== null ||
+    normalized.telemetry.cacheWriteTokens !== null ||
+    normalized.cacheWriteTokensByTtl !== undefined
+      ? {
+          inputTokensDetails: {
+            ...(normalized.telemetry.cachedTokens === null
+              ? {}
+              : { cached_tokens: normalized.telemetry.cachedTokens }),
+            ...(normalized.telemetry.cacheWriteTokens === null
+              ? {}
+              : { cache_write_tokens: normalized.telemetry.cacheWriteTokens }),
+            ...(normalized.cacheWriteTokensByTtl?.fiveMinute == null
+              ? {}
+              : { cache_write_tokens_5m: normalized.cacheWriteTokensByTtl.fiveMinute }),
+            ...(normalized.cacheWriteTokensByTtl?.oneHour == null
+              ? {}
+              : { cache_write_tokens_1h: normalized.cacheWriteTokensByTtl.oneHour }),
+          },
+        }
+      : {}),
+    ...(normalized.requestUsageEntries
+      ? { requestUsageEntries: normalized.requestUsageEntries }
+      : {}),
+  };
+}