@opengeni/core 1.3.0 → 1.4.2

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

@@ -0,0 +1,154 @@
+import type { Settings } from "@opengeni/config";
+import {
+  applyCreditDebitAfterUse,
+  checkWorkspaceAllowance,
+  creditDebitAttributionForTurn,
+  creditDebitAttributionMetadata,
+  getSpendableCreditBalance,
+  recordUsageEvent,
+  withRlsContext,
+  type CreditDebitAttribution,
+  type Database,
+} from "@opengeni/db";
+
+/** 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 function webSearchCreditBillingActive(
+  settings: Pick<Settings, "billingMode" | "usageLimitsMode">,
+): boolean {
+  return settings.billingMode === "stripe" || settings.usageLimitsMode === "managed";
+}
+
+/** 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",
+    message: string,
+  ) {
+    super(message);
+    this.name = "WebSearchBillingRefusedError";
+  }
+}
+
+/**
+ * Admission and post-use settlement for paid web search, matching paid
+ * Knowledge queries and voice input: admission reads 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.
+ */
+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;
+      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;
+      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/index.ts

@@ -7,6 +7,9 @@ export * from "./domain/session-connection-accounts";
 export * from "./domain/organization-integration-catalog";
 export * from "./domain/knowledge";
 export * from "./domain/knowledge-search";
+export * from "./domain/voice-input-billing";
+export * from "./domain/web-search-billing";
+export * from "./domain/realtime-voice-billing";
 // @opengeni/core — the framework-agnostic OpenGeni core.
 //
 // WHAT THIS PACKAGE IS: the OpenGeni domain, access, and billing layers carved

package/src/model-catalog.ts

@@ -39,18 +39,19 @@ import {
 import {
   listConnectionsMetadata,
   getDeploymentModelCatalog,
-  listWorkspaceProviderCustomModels,
+  listWorkspaceProviderCustomModelsByKind,
   getWorkspaceProviderCustomModelForExecution,
   lockActiveWorkspaceProviderCustomModelForAdmission,
   getWorkspaceGatewayCustomModelForExecution,
   getWorkspaceOpenRouterCustomModelForExecution,
   getOrganizationModelProviderCustomModelForExecution,
-  listWorkspaceGatewayCustomModels,
-  listWorkspaceOpenRouterCustomModels,
-  listOrganizationModelProviderCustomModelsForWorkspace,
+  getOrganizationModelProviderCatalogForWorkspace,
   lockActiveOrganizationModelProviderCustomModelForAdmission,
   type OrganizationClaudeModelAdmissionAuthority,
   type Database,
+  type WorkspaceCustomModelProviderKind,
+  type WorkspaceGatewayCustomModel,
+  type WorkspaceOpenRouterCustomModel,
 } from "@opengeni/db";
 
 export type ResolvedCatalogSettings = {
@@ -249,26 +250,34 @@ export async function resolveWorkspaceCatalogSettings(
         ? [productModelId.slice(ORGANIZATION_OPENROUTER_MODEL_ID_PREFIX.length)]
         : [],
   );
+  // One scoped read per catalog family instead of one scoped transaction per
+  // provider kind. The batched readers keep each provider's filters, bound and
+  // overflow error. The Claude subscription flag is env-only (the catalog
+  // document never changes it), so it decides the requested kinds up front.
+  const workspaceCustomModelKinds: WorkspaceCustomModelProviderKind[] = [
+    "vercel_gateway",
+    "openrouter",
+    ...(supportsOrganizationProviderReads
+      ? CLAUDE_CONNECTION_KINDS.filter(
+          (kind) => kind !== "claude_subscription" || envSettings.claudeSubscriptionEnabled,
+        )
+      : []),
+  ];
   const [
     resolved,
-    activeGatewayCustomModels,
-    activeOpenRouterCustomModels,
+    workspaceCustomModels,
     retainedGatewayCustomModels,
     retainedOpenRouterCustomModels,
-    organizationGatewayCustomModels,
-    organizationOpenRouterCustomModels,
+    organizationProviders,
     retainedOrganizationGatewayCustomModels,
     retainedOrganizationOpenRouterCustomModels,
     directConnections,
   ] = await Promise.all([
     resolveCatalogSettings(db, envSettings),
-    listWorkspaceGatewayCustomModels(db, {
-      accountId: input.accountId,
-      workspaceId: input.workspaceId,
-    }),
-    listWorkspaceOpenRouterCustomModels(db, {
+    listWorkspaceProviderCustomModelsByKind(db, {
       accountId: input.accountId,
       workspaceId: input.workspaceId,
+      providerKinds: workspaceCustomModelKinds,
     }),
     Promise.all(
       [...new Set(retainedGatewayUpstreamModelIds)].map(
@@ -291,19 +300,12 @@ export async function resolveWorkspaceCatalogSettings(
       ),
     ),
     supportsOrganizationProviderReads
-      ? listOrganizationModelProviderCustomModelsForWorkspace(db, {
-          accountId: input.accountId,
-          workspaceId: input.workspaceId,
-          providerKind: "vercel_gateway",
-        })
-      : Promise.resolve([]),
-    supportsOrganizationProviderReads
-      ? listOrganizationModelProviderCustomModelsForWorkspace(db, {
+      ? getOrganizationModelProviderCatalogForWorkspace(db, {
           accountId: input.accountId,
           workspaceId: input.workspaceId,
-          providerKind: "openrouter",
+          providerKinds: ["vercel_gateway", "openrouter", ...CLAUDE_CONNECTION_KINDS],
         })
-      : Promise.resolve([]),
+      : null,
     supportsOrganizationProviderReads
       ? Promise.all(
           [...new Set(retainedOrganizationGatewayUpstreamModelIds)].map(
@@ -352,29 +354,25 @@ export async function resolveWorkspaceCatalogSettings(
     return customModels;
   };
   const gatewayCustomModels = includeRetainedModels(
-    activeGatewayCustomModels,
+    workspaceCustomModels.vercel_gateway as WorkspaceGatewayCustomModel[],
     retainedGatewayCustomModels,
   );
   const openRouterCustomModels = includeRetainedModels(
-    activeOpenRouterCustomModels,
+    workspaceCustomModels.openrouter as WorkspaceOpenRouterCustomModel[],
     retainedOpenRouterCustomModels,
   );
   const organizationGatewayModels = includeRetainedModels(
-    organizationGatewayCustomModels,
+    organizationProviders?.vercel_gateway.models ?? [],
     retainedOrganizationGatewayCustomModels,
   );
   const organizationOpenRouterModels = includeRetainedModels(
-    organizationOpenRouterCustomModels,
+    organizationProviders?.openrouter.models ?? [],
     retainedOrganizationOpenRouterCustomModels,
   );
   const claudeConnections: ClaudeConnectionCatalog = {};
-  if (supportsOrganizationProviderReads)
+  if (organizationProviders)
     for (const kind of CLAUDE_CONNECTION_KINDS) {
-      const models = await listOrganizationModelProviderCustomModelsForWorkspace(db, {
-        accountId: input.accountId,
-        workspaceId: input.workspaceId,
-        providerKind: kind,
-      });
+      const models = [...organizationProviders[kind].models];
       const prefix = claudeProviderId(kind) + "/";
       for (const productId of retainedProductModelIds)
         if (productId?.startsWith(prefix)) {
@@ -392,11 +390,7 @@ export async function resolveWorkspaceCatalogSettings(
   if (supportsOrganizationProviderReads)
     for (const kind of CLAUDE_CONNECTION_KINDS) {
       if (kind === "claude_subscription" && !resolved.settings.claudeSubscriptionEnabled) continue;
-      const models = await listWorkspaceProviderCustomModels(db, {
-        accountId: input.accountId,
-        workspaceId: input.workspaceId,
-        providerKind: kind,
-      });
+      const models = [...workspaceCustomModels[kind]];
       const prefix = claudeProviderId(kind, "workspace") + "/";
       for (const productId of retainedProductModelIds) {
         if (!productId?.startsWith(prefix)) continue;

package/src/sandbox/routing.ts

@@ -28,6 +28,7 @@ import {
   readActiveSandbox,
   retainWorkspaceMutationProcess,
   SandboxRetainedProcessPromotionFencedError,
+  SandboxWorkspaceMutationOutputRejectedError,
   retainedProcessSettlementIdentity,
   settleRetainedProcess,
   verifyDirectWorkspaceMutationSettlement,
@@ -43,6 +44,7 @@ import {
   NatsControlRpc,
   NatsOpStreamTransport,
   RoutingSandboxSession,
+  RoutingMutationOutputRejectedError,
   resolveModalCheckpointProviderBindingForSession,
   type ControlRpc,
   type EstablishedSandboxSession,
@@ -359,22 +361,38 @@ export function wrapChannelABoxWithRouting(
           throw new Error(
             "Outcome-unknown command settlement requires its exact retained invocation",
           );
-        await verifyDirectWorkspaceMutationSettlement(db, {
-          accountId: ids.accountId,
-          workspaceId: ids.workspaceId,
-          sessionId: ids.sessionId,
-          requestId: ids.directRequest.requestId,
-          holderId: ids.directRequest.holderId,
-          initiatorSubjectId: ids.resourceSubjectId,
-          sandboxGroupId: homeLease.sandboxGroupId,
-          expectedEpoch: backend.leaseEpoch,
-          expectedInstanceId: backend.providerInstanceId,
-          routeTargetId: exactAdmission.routeTargetId,
-          routeEpoch: exactAdmission.routeEpoch,
-          admission: exactAdmission,
-          operation: op,
-          outcome,
-        });
+        try {
+          await verifyDirectWorkspaceMutationSettlement(db, {
+            accountId: ids.accountId,
+            workspaceId: ids.workspaceId,
+            sessionId: ids.sessionId,
+            requestId: ids.directRequest.requestId,
+            holderId: ids.directRequest.holderId,
+            initiatorSubjectId: ids.resourceSubjectId,
+            sandboxGroupId: homeLease.sandboxGroupId,
+            expectedEpoch: backend.leaseEpoch,
+            expectedInstanceId: backend.providerInstanceId,
+            routeTargetId: exactAdmission.routeTargetId,
+            routeEpoch: exactAdmission.routeEpoch,
+            admission: exactAdmission,
+            operation: op,
+            outcome,
+          });
+        } catch (error) {
+          if (
+            error instanceof SandboxWorkspaceMutationOutputRejectedError &&
+            error.matchesPhysicalSettlement({
+              accountId: ids.accountId,
+              workspaceId: ids.workspaceId,
+              admission: exactAdmission,
+              operation: op,
+              outcome,
+            })
+          ) {
+            throw new RoutingMutationOutputRejectedError(op, error.code, { cause: error });
+          }
+          throw error;
+        }
       }
     : undefined;
   const beforeProcessMutation = homeLease
@@ -419,15 +437,31 @@ export function wrapChannelABoxWithRouting(
         ) {
           throw new Error("API retained-process mutation settlement lacked its exact admission");
         }
-        await verifyRetainedProcessMutationSettlement(db, {
-          accountId: ids.accountId,
-          workspaceId: ids.workspaceId,
-          sessionId: ids.sessionId,
-          processId: process.id,
-          admission: admission as SandboxWorkspaceMutationAdmission,
-          operation: op,
-          outcome,
-        });
+        try {
+          await verifyRetainedProcessMutationSettlement(db, {
+            accountId: ids.accountId,
+            workspaceId: ids.workspaceId,
+            sessionId: ids.sessionId,
+            processId: process.id,
+            admission: admission as SandboxWorkspaceMutationAdmission,
+            operation: op,
+            outcome,
+          });
+        } catch (error) {
+          if (
+            error instanceof SandboxWorkspaceMutationOutputRejectedError &&
+            error.matchesPhysicalSettlement({
+              accountId: ids.accountId,
+              workspaceId: ids.workspaceId,
+              admission: admission as SandboxWorkspaceMutationAdmission,
+              operation: op,
+              outcome,
+            })
+          ) {
+            throw new RoutingMutationOutputRejectedError(op, error.code, { cause: error });
+          }
+          throw error;
+        }
       }
     : undefined;
   const settleProcess = homeLease

package/src/transcription.ts

@@ -1,4 +1,6 @@
+import type { VoiceInputPricing, VoiceInputUsage } from "@opengeni/config";
 import type { TranscribeAudioResponse, VoiceInputErrorCode } from "@opengeni/contracts";
+import type { CreditDebitAttribution } from "@opengeni/db";
 
 /**
  * Server-owned upstream budget for one provider attempt. Resumable recording
@@ -34,6 +36,39 @@ export type TranscriptionRequest = {
   preferredProvider?: string | null | undefined;
   fallbackEnabled?: boolean | undefined;
   excludedProviders?: readonly string[] | undefined;
+  /**
+   * Credit settlement facts for a deployment-funded provider. Required when
+   * the selected provider is deployment-funded and credit billing is active;
+   * the service fails closed without it.
+   */
+  billing?: TranscriptionBillingContext | undefined;
+  /**
+   * Internal: return `settleBilling` instead of settling before returning, so
+   * a resumable segment's transcript commits before any billing write.
+   */
+  deferBillingSettlement?: boolean;
+};
+
+/**
+ * Trusted, server-built settlement identity for one transcription unit. The
+ * usage receipt and debit idempotency keys derive from `workspaceId` +
+ * `sourceId` (see `voiceInputSettlementKeys`), so a retry or a later
+ * reconciliation settles the same unit exactly once.
+ */
+export type TranscriptionBillingContext = {
+  /**
+   * Server-derived unit identity. Never a client-chosen value: a reused id
+   * settles once, so a client-controlled id would make later calls free.
+   */
+  sourceId: string;
+  /** Trusted payer facts from the authenticated request boundary. */
+  attribution: CreditDebitAttribution;
+  /**
+   * Audio duration measured by the server from WAV bytes it produced (the
+   * resumable segment, or the normalized one-shot upload). Bills whenever the
+   * provider reports no usage this deployment has a price for.
+   */
+  trustedDurationSeconds?: number | undefined;
 };
 
 export type TranscriptionResult = TranscribeAudioResponse & {
@@ -41,17 +76,79 @@ export type TranscriptionResult = TranscribeAudioResponse & {
   providerId: string;
   audioSeconds: number;
   latencyMs: number;
+  /** Opengeni credits charged for this call (0 for subscription/free providers). */
+  creditCostMicros?: number | undefined;
+  /**
+   * Server-only settlement callback; never serialized into a public response.
+   * Never rejects: a settlement failure after provider success is logged and
+   * retried, and the transcript is still delivered.
+   */
+  settleBilling?: () => Promise<void>;
+};
+
+export type TranscriptionBillingRefusalCode =
+  | "insufficient_credits"
+  | "allowance_exhausted"
+  | "monthly_model_cost_limit";
+
+/**
+ * Pre-use refusal for deployment-funded transcription: 402 for credits and
+ * allowances (same codes as session admission), 429 for a static monthly cap.
+ */
+export class TranscriptionBillingRefusedError extends Error {
+  readonly status: 402 | 429;
+  readonly code: TranscriptionBillingRefusalCode;
+  readonly details: { scope?: string; resetsAt?: string | null; subjectId?: string };
+
+  constructor(input: {
+    code: TranscriptionBillingRefusalCode;
+    message: string;
+    details?: { scope?: string; resetsAt?: string | null; subjectId?: string };
+  }) {
+    super(input.message);
+    this.name = "TranscriptionBillingRefusedError";
+    this.code = input.code;
+    this.status = input.code === "monthly_model_cost_limit" ? 429 : 402;
+    this.details = input.details ?? {};
+  }
+}
+
+/**
+ * Credit admission and settlement for deployment-funded transcription.
+ * Subscription providers (Codex, SuperGrok) never reach this port.
+ */
+export type TranscriptionBilling = {
+  /** Refuse before any audio is sent when the payer cannot fund the call. */
+  admit(input: {
+    accountId: string;
+    workspaceId: string;
+    attribution: CreditDebitAttribution;
+  }): Promise<void>;
+  /**
+   * Record usage and debit credits once per unit, after use. The usage receipt
+   * commits before the debit, so a failed debit leaves a durable receipt that
+   * `admit` reconciles on the workspace's next voice request.
+   */
+  settle(input: {
+    accountId: string;
+    workspaceId: string;
+    providerId: string;
+    model: string;
+    pricing: VoiceInputPricing;
+    usage: VoiceInputUsage | null;
+    billing: TranscriptionBillingContext;
+  }): Promise<{ creditCostMicros: number }>;
 };
 
 export class TranscriptionServiceError extends Error {
-  readonly code: VoiceInputErrorCode;
+  readonly code: Exclude<VoiceInputErrorCode, TranscriptionBillingRefusalCode>;
   readonly status: number;
   readonly retryable: boolean;
   /** Explicit rejection before any transcription result; safe to try another provider. */
   readonly fallbackSafe: boolean;
 
   constructor(input: {
-    code: VoiceInputErrorCode;
+    code: Exclude<VoiceInputErrorCode, TranscriptionBillingRefusalCode>;
     message: string;
     status?: number;
     retryable?: boolean;
@@ -114,6 +211,14 @@ export type TranscriptionProvider = {
   /** The adapter guarantees that its upstream transport honors AbortSignal. */
   readonly supportsServerDeadline: true;
   readonly experimental?: boolean | undefined;
+  /**
+   * Present when the deployment pays the upstream provider (OpenAI/Azure):
+   * the call is admitted against and settled in Opengeni credits. Absent for
+   * the workspace's own subscriptions, which are never charged.
+   */
+  readonly deploymentFunded?:
+    | { readonly model: string; readonly pricing: VoiceInputPricing | null }
+    | undefined;
   /**
    * Deployment readiness when called without a workspace. When `workspaceId` is
    * provided, providers may require a workspace-attached credential (e.g. Codex).
@@ -128,17 +233,29 @@ export type TranscriptionProvider = {
     subjectId: string;
     requestId: string;
     signal?: AbortSignal | undefined;
-  }): Promise<{ text: string; languages: string[] }>;
+  }): Promise<{ text: string; languages: string[]; usage?: VoiceInputUsage | null | undefined }>;
 };
 
 export type TranscriptionService = {
   limits(): TranscriptionLimits;
   /** True when at least one ready provider can serve requests. */
   available(context?: TranscriptionAvailabilityContext): boolean | Promise<boolean>;
+  availableProviderIds?(context: TranscriptionAvailabilityContext): Promise<string[]>;
   /** Select one provider before a durable segment attempt; retries pin this id. */
   selectProvider?(
     context: TranscriptionAvailabilityContext,
   ): string | null | Promise<string | null>;
+  /**
+   * Credit admission for an exact provider before durable work is claimed.
+   * Resolves for subscription providers; throws TranscriptionBillingRefusedError
+   * when a deployment-funded provider cannot be paid for.
+   */
+  admit?(input: {
+    providerId: string;
+    accountId: string;
+    workspaceId: string;
+    attribution: CreditDebitAttribution;
+  }): Promise<void>;
   transcribe(request: TranscriptionRequest): Promise<TranscriptionResult>;
 };
 
@@ -156,6 +273,8 @@ export type TranscriptionSegmenter = {
     sourceMimeType: string;
     totalDurationMilliseconds: number;
     providerSegmentSeconds: number;
+    /** Hard decode ceiling (`ffmpeg -t`); audio past it is never decoded. */
+    maxDecodeSeconds?: number | undefined;
     chunks: AsyncIterable<Uint8Array>;
     signal?: AbortSignal | undefined;
   }): AsyncIterable<PreparedTranscriptionSegment>;