@opengeni/core 3.0.1 → 3.1.2

package/src/billing/limits.ts

@@ -1,5 +1,6 @@
 import {
   configuredStaticUsageLimits,
+  canonicalizeConfiguredModelId,
   resolveModelProviderForTurn,
   type Settings,
 } from "@opengeni/config";
@@ -11,13 +12,16 @@ import type {
   TurnInitiatorContext,
 } from "@opengeni/contracts";
 import {
+  checkWorkspaceAllowance,
   countActiveApiKeysForWorkspace,
   countActiveOrganizationApiKeysForAccount,
   countScheduledTasksForWorkspace,
   countWorkspacesForAccount,
-  getBillingBalance,
+  getSpendableCreditBalance,
   isCodexBilledTurn,
+  readSubscriptionCoreRouteFunding,
   recordUsageEvent,
+  SUBSCRIPTION_CORE_XAI_PROVIDER,
   sumUsageQuantity,
 } from "@opengeni/db";
 import { HTTPException } from "hono/http-exception";
@@ -25,9 +29,32 @@ import type { ApiRouteDeps } from "../dependencies";
 
 export type LimitDependencies = Pick<ApiRouteDeps, "db" | "settings">;
 
+/** Deterministic/local embeddings never debit credits, even in paid mode. */
+export function paidDocumentEmbedding(settings: Settings): boolean {
+  return (
+    settings.documentEmbeddingBillingMode === "credits" &&
+    settings.documentEmbeddingProvider === "openai"
+  );
+}
+
+/** Round up each provider request so a positive input cannot become a free debit. */
+export function documentEmbeddingCostMicros(settings: Settings, inputBytes: number): number {
+  if (!Number.isSafeInteger(inputBytes) || inputBytes < 0)
+    throw new Error("invalid embedding bytes");
+  const amount =
+    (BigInt(inputBytes) * BigInt(settings.documentEmbeddingRateMicrosPerMillionBytes) + 999_999n) /
+    1_000_000n;
+  if (amount > BigInt(Number.MAX_SAFE_INTEGER))
+    throw new Error("embedding cost exceeds safe integer");
+  return Number(amount);
+}
+
 export type LimitCheckInput = {
   accountId: string;
   workspaceId?: string;
+  /** Frozen causal human, never the API key or service admitting the work. */
+  initiatingHumanSubjectId?: string | null;
+  acceptedTurn?: { sessionId: string; turnId: string };
   action: LimitAction;
   quantity?: number;
   // The turn's model id, when the action represents an agent turn. The model's
@@ -41,6 +68,12 @@ export function modelFundingForAdmission(
   settings: Settings,
   model: string | null | undefined,
   codexBilled: boolean,
+  /**
+   * The shared core's live funding answer for a connected subscription that
+   * has cut over to the core (`coreRoutedSubscriptionFunding`); undefined
+   * keeps the legacy answer.
+   */
+  coreRoutedFunding?: boolean,
 ): { fundedWithoutCredits: boolean; countsTowardTokenCap: boolean } {
   const resolvedModel = model ? resolveModelProviderForTurn(settings, model)?.model : null;
   const codexSubscriptionModel =
@@ -48,25 +81,81 @@ export function modelFundingForAdmission(
     resolvedModel.credentialSource.provider === "codex";
   return {
     // A Codex namespace/definition never bypasses credits by itself: the live
-    // workspace credential predicate above remains authoritative. SuperGrok's
-    // static overlay is likewise secret-free; its worker/provider admission
-    // owns live account selection before any upstream request can occur.
+    // workspace credential predicate above remains authoritative. Claude's
+    // static overlay is likewise secret-free on its legacy route; its
+    // worker/provider admission owns live account selection before any
+    // upstream request can occur. On the core route (the only SuperGrok
+    // route) the core's funding answer is authoritative instead.
     fundedWithoutCredits:
       codexBilled ||
-      (resolvedModel != null && !codexSubscriptionModel && resolvedModel.cost !== "credits"),
+      (coreRoutedFunding ??
+        (resolvedModel != null && !codexSubscriptionModel && resolvedModel.cost !== "credits")),
     countsTowardTokenCap:
       !codexBilled && resolvedModel != null && resolvedModel.billing.upstreamPayer === "deployment",
   };
 }
 
+/**
+ * Connected subscriptions whose legacy runtime was deleted after their
+ * cutover: only the shared core funds them, so any other route is unfunded.
+ */
+const CORE_ONLY_SUBSCRIPTION_PROVIDERS: ReadonlySet<string> = new Set([
+  SUBSCRIPTION_CORE_XAI_PROVIDER,
+]);
+
+/**
+ * The shared core's funding answer for a non-Codex connected subscription
+ * whose provider has cut over (design 5.3, EP-N19): the provider-neutral form
+ * of `isCodexBilledTurn`, with explicit workspace, causal human, accepted
+ * work and model. Undefined on the provider's legacy route (one receipt
+ * read) and for every other model (no read). Codex keeps `isCodexBilledTurn`.
+ * A provider opts in at its own chat placement step and only while it is
+ * enabled on the deployment, as its catalog readiness does.
+ */
+const CORE_ROUTED_FUNDING: Partial<Record<string, (settings: Settings) => boolean>> = {
+  xai: (settings) => settings.supergrokSubscriptionEnabled,
+  claude: (settings) => settings.claudeSubscriptionEnabled,
+};
+
+export async function coreRoutedSubscriptionFunding(
+  db: LimitDependencies["db"],
+  settings: Settings,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    model: string | null | undefined;
+    subjectId: string | null;
+    acceptedTurn?: { sessionId: string; turnId: string };
+  },
+): Promise<boolean | undefined> {
+  if (!input.model) return undefined;
+  const source = resolveModelProviderForTurn(settings, input.model)?.model.credentialSource;
+  if (source?.kind !== "connected_subscription") return undefined;
+  if (!CORE_ROUTED_FUNDING[source.provider]?.(settings)) return undefined;
+  const answer = await readSubscriptionCoreRouteFunding(db, {
+    provider: source.provider,
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    subjectId: input.subjectId,
+    productModelId: input.model,
+    ...(input.acceptedTurn ? { acceptedTurn: input.acceptedTurn } : {}),
+  });
+  if (answer.route === "core") return answer.value;
+  return CORE_ONLY_SUBSCRIPTION_PROVIDERS.has(source.provider) ? false : undefined;
+}
+
 export async function requireLimit(deps: LimitDependencies, input: LimitCheckInput): Promise<void> {
   const decision = await checkLimit(deps, input);
   if (decision.allowed) {
     return;
   }
-  throw new HTTPException(decision.code === "insufficient_credits" ? 402 : 429, {
-    message: decision.message,
-  });
+  throw new HTTPException(
+    decision.code === "insufficient_credits" || decision.code === "allowance_exhausted" ? 402 : 429,
+    {
+      message: decision.message,
+      cause: decision,
+    },
+  );
 }
 
 export async function checkLimit(
@@ -82,17 +171,41 @@ export async function checkLimit(
         settings: deps.settings,
         workspaceId: input.workspaceId,
         model: input.model,
+        // On the shared Codex core the causal human's own personal
+        // connection in their Personal workspace also funds the turn.
+        accountId: input.accountId,
+        subjectId: input.initiatingHumanSubjectId ?? null,
+        ...(input.acceptedTurn ? { acceptedTurn: input.acceptedTurn } : {}),
       })
     : false;
+  const coreFunding = input.workspaceId
+    ? await coreRoutedSubscriptionFunding(deps.db, deps.settings, {
+        accountId: input.accountId,
+        workspaceId: input.workspaceId,
+        model: input.model,
+        subjectId: input.initiatingHumanSubjectId ?? null,
+        ...(input.acceptedTurn ? { acceptedTurn: input.acceptedTurn } : {}),
+      })
+    : undefined;
   const { fundedWithoutCredits, countsTowardTokenCap } = modelFundingForAdmission(
     deps.settings,
     input.model,
     codexBilled,
+    coreFunding,
   );
   const creditDecision = await checkCreditBalance(deps, input, fundedWithoutCredits);
   if (!creditDecision.allowed) {
     return creditDecision;
   }
+  if (isCostlyAction(input.action) && input.workspaceId) {
+    const refusal = await checkWorkspaceAllowance(deps.db, {
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      subjectId: input.initiatingHumanSubjectId ?? null,
+      ...(fundedWithoutCredits ? { fundedWithoutCredits: true } : {}),
+    });
+    if (refusal) return { allowed: false, ...refusal };
+  }
   if (deps.settings.usageLimitsMode !== "static" && deps.settings.usageLimitsMode !== "managed") {
     return { allowed: true };
   }
@@ -108,16 +221,26 @@ async function checkCreditBalance(
   externallyBilled: boolean,
 ): Promise<LimitDecision> {
   if (externallyBilled) {
-    return { allowed: true }; // paid outside OpenGeni — zero OpenGeni credits
+    return { allowed: true }; // paid outside Opengeni — zero Opengeni credits
   }
   if (!usesCreditLimits(deps) || !isCostlyAction(input.action)) {
     return { allowed: true };
   }
-  const balance = await getBillingBalance(deps.db, input.accountId);
+  const balance = await getSpendableCreditBalance(
+    deps.db,
+    input.accountId,
+    input.model ? canonicalizeConfiguredModelId(deps.settings, input.model) : undefined,
+  );
   if (balance.balanceMicros > 0) {
     return { allowed: true };
   }
-  return { allowed: false, code: "insufficient_credits", message: "insufficient OpenGeni credits" };
+  return {
+    allowed: false,
+    code: "insufficient_credits",
+    message: input.model
+      ? "No credits available for this model. Choose a model covered by your promotional credits or add credits."
+      : "No general credits available. Promotional credits cover eligible models only.",
+  };
 }
 
 async function checkStaticCaps(
@@ -296,9 +419,10 @@ function usesCreditLimits(deps: LimitDependencies): boolean {
 }
 
 function isCostlyAction(action: LimitAction): boolean {
-  return (
-    action === "agent_run:create" || action === "tokens:consume" || action === "document:index"
-  );
+  // Document admission retains the monthly chunk quota above, but parsing and
+  // source retention do not consume embedding credits. The worker admits paid
+  // embedding separately and settles its actual provider input after use.
+  return action === "agent_run:create" || action === "tokens:consume";
 }
 
 function blocked(code: string, message: string): LimitDecision {

package/src/billing/model-call-admission.ts

@@ -0,0 +1,118 @@
+import { configuredStaticUsageLimits, type Settings } from "@opengeni/config";
+import type { EntitlementsPort } from "@opengeni/contracts";
+import {
+  checkWorkspaceAllowance,
+  getSpendableCreditBalance,
+  sumUsageQuantity,
+  type Database,
+} from "@opengeni/db";
+
+export type ModelCallAdmissionDenial =
+  | "insufficient_credits"
+  | "allowance_exhausted"
+  | "monthly_model_cost_limit"
+  | "monthly_token_limit";
+
+export type ModelCallAdmission =
+  | { allowed: true; creditPolicyRevision: number | undefined }
+  | { allowed: false; denial: ModelCallAdmissionDenial; message: string };
+
+/**
+ * Admission for one stateless model call, with the same funding rules as an
+ * agent turn between model calls: an Opengeni-credit model needs a positive
+ * spendable balance, the workspace allowance must not be exhausted, and the
+ * static monthly caps apply. Admission is a read, never a reservation or an
+ * estimate of the call's cost; settlement charges actual usage afterwards.
+ * Externally funded calls (subscriptions, workspace or organization keys)
+ * skip the credit gate and the token cap.
+ */
+export async function admitModelCall(
+  services: { db: Database; settings: Settings; entitlements?: EntitlementsPort | null },
+  input: {
+    accountId: string;
+    workspaceId: string;
+    /** Canonical product model id; scopes model-specific promotional credits. */
+    model: string;
+    chargesOpenGeniCredits: boolean;
+    countsTowardTokenCap: boolean;
+    subjectId: string | null;
+  },
+): Promise<ModelCallAdmission> {
+  const { settings, db } = services;
+  const metered = settings.billingMode === "stripe" || settings.usageLimitsMode === "managed";
+  let creditPolicyRevision: number | undefined;
+  if (input.chargesOpenGeniCredits && metered) {
+    if (services.entitlements) {
+      const decision = await services.entitlements.admitRun({
+        accountId: input.accountId,
+        workspaceId: input.workspaceId,
+        action: "model_call:create",
+        quantity: 1,
+      });
+      if (!decision.allowed) {
+        return {
+          allowed: false,
+          denial: "insufficient_credits",
+          message: decision.reason || "Insufficient Opengeni credits.",
+        };
+      }
+    } else {
+      const balance = await getSpendableCreditBalance(db, input.accountId, input.model);
+      creditPolicyRevision = balance.creditPolicyRevision;
+      if (balance.balanceMicros <= 0) {
+        return {
+          allowed: false,
+          denial: "insufficient_credits",
+          message: "Insufficient Opengeni credits.",
+        };
+      }
+    }
+  }
+  const refusal = await checkWorkspaceAllowance(db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    subjectId: input.subjectId,
+    ...(input.chargesOpenGeniCredits ? {} : { fundedWithoutCredits: true }),
+  });
+  if (refusal) {
+    return { allowed: false, denial: "allowance_exhausted", message: refusal.message };
+  }
+  if (settings.usageLimitsMode === "static" || settings.usageLimitsMode === "managed") {
+    const limits = configuredStaticUsageLimits(settings);
+    const since = startOfUtcMonth();
+    if (input.chargesOpenGeniCredits && limits.maxMonthlyCostMicrosPerAccount) {
+      const used = await sumUsageQuantity(db, {
+        accountId: input.accountId,
+        eventType: "model.cost",
+        since,
+      });
+      if (used >= limits.maxMonthlyCostMicrosPerAccount) {
+        return {
+          allowed: false,
+          denial: "monthly_model_cost_limit",
+          message: "The monthly model cost limit has been reached.",
+        };
+      }
+    }
+    if (input.countsTowardTokenCap && limits.maxMonthlyTokensPerWorkspace) {
+      const used = await sumUsageQuantity(db, {
+        workspaceId: input.workspaceId,
+        eventType: "model.tokens",
+        since,
+      });
+      if (used >= limits.maxMonthlyTokensPerWorkspace) {
+        return {
+          allowed: false,
+          denial: "monthly_token_limit",
+          message: "The monthly token limit has been reached.",
+        };
+      }
+    }
+  }
+  return { allowed: true, creditPolicyRevision };
+}
+
+function startOfUtcMonth(): Date {
+  const now = new Date();
+  return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1));
+}