@opengeni/core 3.0.1 → 3.1.2

package/src/domain/voice-input-billing.ts

@@ -0,0 +1,330 @@
+import {
+  calculateVoiceInputCost,
+  configuredStaticUsageLimits,
+  voiceInputCreditBillingActive,
+  voiceInputPricingHasTokenRates,
+  type Settings,
+  type VoiceInputPricing,
+  type VoiceInputUsage,
+} from "@opengeni/config";
+import {
+  applyCreditDebitAfterUse,
+  checkWorkspaceAllowance,
+  creditDebitAttributionMetadata,
+  getSpendableCreditBalance,
+  listUnsettledVoiceTranscriptionCharges,
+  recordUsageEvent,
+  sumUsageQuantity,
+  VOICE_TRANSCRIPTION_DEBIT_TYPE,
+  VOICE_TRANSCRIPTION_SOURCE_TYPE,
+  voiceTranscriptionSettlementKeys,
+  VOICE_CREDIT_USAGE,
+  type CreditDebitAttribution,
+  type Database,
+} from "@opengeni/db";
+import {
+  TranscriptionBillingRefusedError,
+  TranscriptionServiceError,
+  type TranscriptionBilling,
+  type TranscriptionBillingContext,
+} from "../transcription";
+import {
+  voiceCreditStanding,
+  voiceInsufficientCreditsMessage,
+  workspaceCreditsDisabled,
+} from "./realtime-voice-billing";
+
+/** Credit debit type and usage source for deployment-funded voice input. */
+export const VOICE_INPUT_DEBIT_TYPE = VOICE_TRANSCRIPTION_DEBIT_TYPE;
+export const VOICE_INPUT_SOURCE_TYPE = VOICE_TRANSCRIPTION_SOURCE_TYPE;
+
+/** How the billed quantity was measured; recorded on the ledger entry. */
+export type VoiceInputBillingBasis =
+  | "provider_tokens"
+  | "provider_duration"
+  | "server_duration"
+  | "reconciled_receipt";
+
+/**
+ * Pick the billed measurement. Provider usage wins when this deployment can
+ * price it (token usage with token rates, or a reported duration). Otherwise
+ * the duration the server measured from WAV bytes it produced bills. Every
+ * deployment-funded call carries that server duration, so an unpriced usage
+ * shape never leaves a call unbillable. A client-reported duration is never a
+ * billing input.
+ */
+export function voiceInputBillableUsage(input: {
+  pricing: VoiceInputPricing;
+  usage: VoiceInputUsage | null;
+  trustedDurationSeconds?: number | undefined;
+}): { usage: VoiceInputUsage; basis: VoiceInputBillingBasis } {
+  if (input.usage?.kind === "tokens" && voiceInputPricingHasTokenRates(input.pricing)) {
+    return { usage: input.usage, basis: "provider_tokens" };
+  }
+  if (input.usage?.kind === "duration") {
+    return { usage: input.usage, basis: "provider_duration" };
+  }
+  if (
+    input.trustedDurationSeconds !== undefined &&
+    Number.isFinite(input.trustedDurationSeconds) &&
+    input.trustedDurationSeconds >= 0
+  ) {
+    return {
+      usage: { kind: "duration", seconds: input.trustedDurationSeconds },
+      basis: "server_duration",
+    };
+  }
+  throw new TranscriptionServiceError({
+    code: "provider",
+    message: "Transcription usage was not reported.",
+  });
+}
+
+function initiatingHuman(attribution: CreditDebitAttribution): string | null {
+  return attribution.kind === "human" || attribution.kind === "turn"
+    ? attribution.initiatingHumanSubjectId
+    : null;
+}
+
+function startOfUtcMonth(): Date {
+  const now = new Date();
+  return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1));
+}
+
+/**
+ * Same admission shape as knowledge-search and session admission:
+ * voice-spendable credits (general plus signup, not model-scoped promotional
+ * credits) must be positive, the workspace/member
+ * allowance must not be exhausted, and a static monthly cost cap applies.
+ * Admission is a read, not a reservation; settlement is post-use and may take
+ * an account below zero by at most the concurrent in-flight calls.
+ */
+export function createVoiceInputBilling(deps: {
+  db: Database;
+  settings: Settings;
+  /** Reconciliation is best-effort at admission; failures are reported here. */
+  onReconcileError?: (error: unknown, scope: { accountId: string; workspaceId: string }) => void;
+  /** Minimum spacing of admission-time reconciliation per workspace (default 5 min). */
+  reconcileIntervalMilliseconds?: number;
+}): TranscriptionBilling {
+  const reconcileInterval = deps.reconcileIntervalMilliseconds ?? 5 * 60_000;
+  const lastReconciled = new Map<string, number>();
+  const reconcileDue = (key: string) => {
+    const now = Date.now();
+    const last = lastReconciled.get(key);
+    if (last !== undefined && now - last < reconcileInterval) return false;
+    if (lastReconciled.size >= 10_000) lastReconciled.clear();
+    lastReconciled.set(key, now);
+    return true;
+  };
+  return {
+    async admit({ accountId, workspaceId, attribution }) {
+      if (!voiceInputCreditBillingActive(deps.settings)) return;
+      if (attribution.kind === "unknown") {
+        // Not a microphone problem: the caller's credential has no payer the
+        // ledger can attribute, so the deployment refuses by policy.
+        throw new TranscriptionServiceError({
+          code: "policy_blocked",
+          status: 403,
+          message: "Voice input payer could not be verified.",
+        });
+      }
+      // Deployment-paid voice input spends Opengeni credits, so it honors the
+      // workspace switch that turns them off. Nothing was sent yet, so another
+      // (subscription) provider may still serve the request.
+      if (await workspaceCreditsDisabled(deps.db, workspaceId)) {
+        throw new TranscriptionServiceError({
+          code: "policy_blocked",
+          status: 403,
+          fallbackSafe: true,
+          message: "Opengeni credits are turned off in this workspace.",
+        });
+      }
+      // Debits whose receipt committed but whose ledger write failed are
+      // applied before the balance read, so unsettled use counts against it.
+      // Throttled per workspace: failed debits are rare, the scan is not free.
+      if (reconcileDue(`${accountId}:${workspaceId}`)) {
+        await reconcileUnsettledVoiceInputCharges(deps.db, { accountId, workspaceId }).catch(
+          (error: unknown) => {
+            deps.onReconcileError?.(error, { accountId, workspaceId });
+          },
+        );
+      }
+      const balance = await getSpendableCreditBalance(deps.db, accountId, VOICE_CREDIT_USAGE);
+      if (balance.balanceMicros <= 0) {
+        throw new TranscriptionBillingRefusedError({
+          code: "insufficient_credits",
+          message: voiceInsufficientCreditsMessage("Voice input", voiceCreditStanding(balance)),
+        });
+      }
+      const refusal = await checkWorkspaceAllowance(deps.db, {
+        accountId,
+        workspaceId,
+        subjectId: initiatingHuman(attribution),
+      });
+      if (refusal) {
+        throw new TranscriptionBillingRefusedError({
+          code: refusal.code,
+          message: refusal.message,
+          details: {
+            scope: refusal.scope,
+            resetsAt: refusal.resetsAt,
+            ...(refusal.subjectId ? { subjectId: refusal.subjectId } : {}),
+          },
+        });
+      }
+      if (
+        deps.settings.usageLimitsMode === "static" ||
+        deps.settings.usageLimitsMode === "managed"
+      ) {
+        const cap = configuredStaticUsageLimits(deps.settings).maxMonthlyCostMicrosPerAccount;
+        if (cap) {
+          const used = await sumUsageQuantity(deps.db, {
+            accountId,
+            eventType: "model.cost",
+            since: startOfUtcMonth(),
+          });
+          if (used >= cap) {
+            throw new TranscriptionBillingRefusedError({
+              code: "monthly_model_cost_limit",
+              message: "The monthly model cost limit has been reached.",
+            });
+          }
+        }
+      }
+    },
+
+    async settle(input) {
+      if (!voiceInputCreditBillingActive(deps.settings)) return { creditCostMicros: 0 };
+      const { usage, basis } = voiceInputBillableUsage({
+        pricing: input.pricing,
+        usage: input.usage,
+        trustedDurationSeconds: input.billing.trustedDurationSeconds,
+      });
+      const cost = calculateVoiceInputCost(input.pricing, usage);
+      return await settleVoiceInputUsage(deps.db, {
+        accountId: input.accountId,
+        workspaceId: input.workspaceId,
+        providerId: input.providerId,
+        model: input.model,
+        billing: input.billing,
+        usage,
+        basis,
+        providerCostMicros: cost.providerCostMicros,
+        creditCostMicros: cost.creditCostMicros,
+      });
+    },
+  };
+}
+
+/**
+ * Two commits, in order: the `model.cost` usage receipt (Insights spend,
+ * monthly cost cap, member-allowance attribution), then the post-use credit
+ * debit. The receipt is the first-writer authority for the amount and the
+ * durable record of the charge: if the debit commit fails, the receipt stays
+ * and {@link reconcileUnsettledVoiceInputCharges} applies the same debit (same
+ * idempotency key) on the workspace's next admission. A retried unit settles
+ * exactly once at the originally recorded price.
+ */
+export async function settleVoiceInputUsage(
+  db: Database,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    providerId: string;
+    model: string;
+    billing: TranscriptionBillingContext;
+    usage: VoiceInputUsage;
+    basis: VoiceInputBillingBasis;
+    providerCostMicros: number;
+    creditCostMicros: number;
+  },
+): Promise<{ creditCostMicros: number }> {
+  const attribution = input.billing.attribution;
+  const keys = voiceTranscriptionSettlementKeys({
+    workspaceId: input.workspaceId,
+    sourceId: input.billing.sourceId,
+  });
+  const receipt = await recordUsageEvent(db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    eventType: "model.cost",
+    quantity: input.creditCostMicros,
+    unit: "usd_micros",
+    sourceResourceType: VOICE_TRANSCRIPTION_SOURCE_TYPE,
+    sourceResourceId: input.billing.sourceId,
+    idempotencyKey: keys.usageIdempotencyKey,
+    // The API is the writer; the payer is the trusted attribution snapshot.
+    initiator: { kind: "service", subjectId: "api:voice-input" },
+    initiatorContext: { creditDebitAttribution: attribution },
+  });
+  const amount = Number(receipt.quantity);
+  if (amount > 0) {
+    await applyCreditDebitAfterUse(db, {
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      type: VOICE_TRANSCRIPTION_DEBIT_TYPE,
+      amountMicros: amount,
+      sourceType: VOICE_TRANSCRIPTION_SOURCE_TYPE,
+      sourceId: input.billing.sourceId,
+      idempotencyKey: keys.debitIdempotencyKey,
+      usage: VOICE_CREDIT_USAGE,
+      metadata: {
+        providerId: input.providerId,
+        model: input.model,
+        basis: input.basis,
+        providerCostMicros: input.providerCostMicros,
+        ...(input.usage.kind === "tokens"
+          ? {
+              inputTokens: input.usage.inputTokens,
+              audioInputTokens: input.usage.audioInputTokens,
+              textInputTokens: input.usage.textInputTokens,
+              outputTokens: input.usage.outputTokens,
+            }
+          : { audioMilliseconds: Math.ceil(input.usage.seconds * 1_000) }),
+        ...(attribution.kind === "unknown" ? {} : creditDebitAttributionMetadata(attribution)),
+      },
+    });
+  }
+  return { creditCostMicros: amount };
+}
+
+/**
+ * Apply the debit for every voice usage receipt in this workspace whose debit
+ * never committed. Idempotent with the inline settlement (same key), bounded
+ * per call, and safe to run concurrently.
+ */
+export async function reconcileUnsettledVoiceInputCharges(
+  db: Database,
+  input: { accountId: string; workspaceId: string; minAgeMilliseconds?: number },
+): Promise<{ reconciled: number }> {
+  const pending = await listUnsettledVoiceTranscriptionCharges(db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    ...(input.minAgeMilliseconds !== undefined
+      ? { minAgeMilliseconds: input.minAgeMilliseconds }
+      : {}),
+  });
+  for (const charge of pending) {
+    await applyCreditDebitAfterUse(db, {
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      type: VOICE_TRANSCRIPTION_DEBIT_TYPE,
+      amountMicros: charge.amountMicros,
+      sourceType: VOICE_TRANSCRIPTION_SOURCE_TYPE,
+      sourceId: charge.sourceId,
+      idempotencyKey: voiceTranscriptionSettlementKeys({
+        workspaceId: input.workspaceId,
+        sourceId: charge.sourceId,
+      }).debitIdempotencyKey,
+      usage: VOICE_CREDIT_USAGE,
+      metadata: {
+        basis: "reconciled_receipt" satisfies VoiceInputBillingBasis,
+        ...(charge.attribution.kind === "unknown"
+          ? {}
+          : creditDebitAttributionMetadata(charge.attribution)),
+      },
+    });
+  }
+  return { reconciled: pending.length };
+}

package/src/domain/web-search-billing.ts

@@ -0,0 +1,169 @@
+import { webSearchCreditBillingActive, type Settings } from "@opengeni/config";
+import {
+  applyCreditDebitAfterUse,
+  checkWorkspaceAllowance,
+  creditDebitAttributionForTurn,
+  creditDebitAttributionMetadata,
+  getSpendableCreditBalance,
+  recordUsageEvent,
+  withRlsContext,
+  type CreditDebitAttribution,
+  type Database,
+} from "@opengeni/db";
+import { workspaceCreditsDisabled } from "./workspace-credits";
+
+/** Credit ledger type and usage source for deployment-funded web search calls. */
+export const WEB_SEARCH_DEBIT_TYPE = "web_search_debit";
+export const WEB_SEARCH_SOURCE_TYPE = "web_search";
+const WEB_SEARCH_BILLING_INITIATOR = "worker:web-search";
+
+/** Same rule as other deployment-funded resources: Stripe or managed limits. */
+export { webSearchCreditBillingActive } from "@opengeni/config";
+
+/** Exact attempt that called the tool. Every charge is attributed to its turn. */
+export type WebSearchCallScope = {
+  accountId: string;
+  workspaceId: string;
+  sessionId: string;
+  turnId: string;
+  attemptId: string;
+};
+
+export type WebSearchCallCost = {
+  /** Model tool-call or Codemode operation identity, unique within the attempt. */
+  operationId: string;
+  operation: "search" | "fetch";
+  provider: string;
+  providerMicros: number;
+  creditMicros: number;
+  marginBps: number;
+  basis: "provider_reported" | "configured_price" | "list_price";
+};
+
+export class WebSearchBillingRefusedError extends Error {
+  constructor(
+    readonly code: "insufficient_credits" | "allowance_exhausted" | "credits_disabled",
+    message: string,
+  ) {
+    super(message);
+    this.name = "WebSearchBillingRefusedError";
+  }
+}
+
+/** Model-facing refusal when the workspace turned Opengeni credits off. */
+export const WEB_SEARCH_CREDITS_DISABLED_MESSAGE =
+  "Web search uses Opengeni credits, which are turned off in this workspace.";
+
+/**
+ * Admission and post-use settlement for paid web search, matching paid
+ * Knowledge queries and voice input: admission reads the workspace credit
+ * switch, general credits and the workspace/member allowance (a read, not a
+ * reservation); settlement records a durable usage receipt and the idempotent
+ * debit in one transaction. Calls that cost nothing (free providers, or
+ * billing inactive) are never refused. A workspace that turned Opengeni
+ * credits off is refused paid calls, and settlement skips the debit (and the
+ * cost receipt) for a call that was in flight when the switch turned off or
+ * that was admitted as free but reported a provider cost.
+ */
+export function createWebSearchBilling(deps: { db: Database; settings: Settings }) {
+  const active = webSearchCreditBillingActive(deps.settings);
+  const attributionByTurn = new Map<string, Promise<CreditDebitAttribution>>();
+  const attributionFor = (scope: WebSearchCallScope) => {
+    let attribution = attributionByTurn.get(scope.turnId);
+    if (!attribution) {
+      attribution = creditDebitAttributionForTurn(deps.db, scope);
+      attributionByTurn.set(scope.turnId, attribution);
+      attribution.catch(() => attributionByTurn.delete(scope.turnId));
+    }
+    return attribution;
+  };
+  return {
+    active,
+    async admit(scope: WebSearchCallScope, expectedProviderMicros: number): Promise<void> {
+      if (!active || expectedProviderMicros <= 0) return;
+      if (await workspaceCreditsDisabled(deps.db, scope.workspaceId)) {
+        throw new WebSearchBillingRefusedError(
+          "credits_disabled",
+          WEB_SEARCH_CREDITS_DISABLED_MESSAGE,
+        );
+      }
+      const attribution = await attributionFor(scope);
+      // Non-model resources spend general credits only.
+      const balance = await getSpendableCreditBalance(deps.db, scope.accountId);
+      if (balance.balanceMicros <= 0) {
+        throw new WebSearchBillingRefusedError(
+          "insufficient_credits",
+          "Web search needs Opengeni credits, and this account has none left.",
+        );
+      }
+      const refusal = await checkWorkspaceAllowance(deps.db, {
+        accountId: scope.accountId,
+        workspaceId: scope.workspaceId,
+        subjectId: attribution.kind === "turn" ? attribution.initiatingHumanSubjectId : null,
+      });
+      if (refusal) throw new WebSearchBillingRefusedError("allowance_exhausted", refusal.message);
+    },
+    async settle(scope: WebSearchCallScope, cost: WebSearchCallCost): Promise<void> {
+      const shared = {
+        accountId: scope.accountId,
+        workspaceId: scope.workspaceId,
+        sessionId: scope.sessionId,
+        turnId: scope.turnId,
+        turnAttemptId: scope.attemptId,
+        sourceResourceType: WEB_SEARCH_SOURCE_TYPE,
+        sourceResourceId: `${scope.attemptId}:${cost.operationId}`,
+      };
+      // Request counts are recorded for every deployment, billed or not, so
+      // operators see provider volume.
+      await recordUsageEvent(deps.db, {
+        ...shared,
+        eventType: `web_search.${cost.operation}_requests`,
+        quantity: 1,
+        unit: "request",
+        idempotencyKey: `usage:web_search.${cost.operation}_requests:${shared.sourceResourceId}`,
+      });
+      if (!active || cost.creditMicros <= 0) return;
+      // Admission refused paid calls already; this covers a switch turned off
+      // during the provider call and provider-reported cost on a call admitted
+      // as free. The workspace spends no credits; the request count stays.
+      if (await workspaceCreditsDisabled(deps.db, scope.workspaceId)) return;
+      const attribution = await attributionFor(scope);
+      await withRlsContext(
+        deps.db,
+        { accountId: scope.accountId, workspaceId: scope.workspaceId },
+        async (tx) => {
+          await recordUsageEvent(tx, {
+            ...shared,
+            eventType: "web_search.cost",
+            quantity: cost.creditMicros,
+            unit: "usd_micros",
+            idempotencyKey: `usage:web_search.cost:${shared.sourceResourceId}`,
+            initiator: { kind: "service", subjectId: WEB_SEARCH_BILLING_INITIATOR },
+            initiatorContext: { creditDebitAttribution: attribution },
+          });
+          await applyCreditDebitAfterUse(tx, {
+            accountId: scope.accountId,
+            workspaceId: scope.workspaceId,
+            type: WEB_SEARCH_DEBIT_TYPE,
+            amountMicros: cost.creditMicros,
+            sourceType: WEB_SEARCH_SOURCE_TYPE,
+            sourceId: shared.sourceResourceId,
+            idempotencyKey: `credit:${WEB_SEARCH_DEBIT_TYPE}:${shared.sourceResourceId}`,
+            metadata: {
+              // turnId lets the allowance trigger resolve the causal human
+              // from the immutable turn receipt.
+              ...creditDebitAttributionMetadata(attribution),
+              provider: cost.provider,
+              operation: cost.operation,
+              providerCostMicros: cost.providerMicros,
+              marginBps: cost.marginBps,
+              basis: cost.basis,
+            },
+          });
+        },
+      );
+    },
+  };
+}
+
+export type WebSearchBilling = ReturnType<typeof createWebSearchBilling>;

package/src/domain/workspace-credits.ts

@@ -0,0 +1,13 @@
+import { getWorkspaceModelPolicy, type Database } from "@opengeni/db";
+
+/**
+ * True when the workspace turned Opengeni credits off. Every meter that would
+ * spend credits (credit-billed models, voice, web search, knowledge
+ * embeddings) honors this one switch.
+ */
+export async function workspaceCreditsDisabled(
+  db: Database,
+  workspaceId: string,
+): Promise<boolean> {
+  return (await getWorkspaceModelPolicy(db, workspaceId))?.allowCreditModels === false;
+}

package/src/editable-artifact-live/application.ts

@@ -19,7 +19,10 @@ import type {
   EditableArtifactLiveServer,
   OpenEditableArtifactLiveInput,
 } from "./server";
-import type { EditableArtifactLiveTicket } from "./types";
+import type {
+  EditableArtifactLiveSourceSessionAuthority,
+  EditableArtifactLiveTicket,
+} from "./types";
 
 export type EditableArtifactLiveCompatibilityRequest = Readonly<{
   artifact: EditableArtifact;
@@ -83,6 +86,7 @@ export type MintEditableArtifactApplicationTicketInput = ReadEditableArtifactApp
     commandProtocolVersion: number;
     committedTransactionProtocolVersion: number;
     allowEdit: boolean;
+    sourceSessionAuthority?: EditableArtifactLiveSourceSessionAuthority;
   }>;
 
 /** Exact application seam used by standalone API and embedding hosts. */
@@ -176,6 +180,9 @@ export class EditableArtifactApplication implements EditableArtifactApplicationP
       modality: artifact.modality,
       actor: input.actor,
       allowEdit: input.allowEdit,
+      ...(input.sourceSessionAuthority
+        ? { sourceSessionAuthority: input.sourceSessionAuthority }
+        : {}),
     });
   }