@opengeni/core 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/core",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "OpenGeni framework-agnostic core: the domain, access, and billing layers (neutral access, off-HTTP V2 surface). Behavior-preserving extraction from apps/api — keeps Hono's HTTPException for error throwing (typed-errors cleanup deferred).",
   "license": "Apache-2.0",
   "repository": {
@@ -50,17 +50,17 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opengeni/capabilities": "1.1.0",
-    "@opengeni/codex": "1.1.0",
-    "@opengeni/config": "1.1.0",
-    "@opengeni/contracts": "1.1.0",
-    "@opengeni/db": "1.1.0",
-    "@opengeni/documents": "1.1.0",
-    "@opengeni/events": "1.1.0",
-    "@opengeni/network": "1.1.0",
-    "@opengeni/observability": "1.1.0",
-    "@opengeni/runtime": "1.1.0",
-    "@opengeni/storage": "1.1.0",
+    "@opengeni/capabilities": "1.2.0",
+    "@opengeni/codex": "1.2.0",
+    "@opengeni/config": "1.2.0",
+    "@opengeni/contracts": "1.2.0",
+    "@opengeni/db": "1.2.0",
+    "@opengeni/documents": "1.2.0",
+    "@opengeni/events": "1.2.0",
+    "@opengeni/network": "1.2.0",
+    "@opengeni/observability": "1.2.0",
+    "@opengeni/runtime": "1.2.0",
+    "@opengeni/storage": "1.2.0",
     "hono": "^4.12.18",
     "zod": "^4.2.1"
   },

package/src/billing/agent-run-admission.ts

@@ -1,9 +1,13 @@
-import { configuredStaticUsageLimits, type Settings } from "@opengeni/config";
+import {
+  canonicalizeConfiguredModelId,
+  configuredStaticUsageLimits,
+  type Settings,
+} from "@opengeni/config";
 import type { EntitlementsPort } from "@opengeni/contracts";
 import { modelFundingForAdmission } from "./limits";
 import {
   checkWorkspaceAllowance,
-  getBillingBalance,
+  getSpendableCreditBalance,
   isCodexBilledTurn,
   sumUsageQuantity,
   type Database,
@@ -51,7 +55,11 @@ export async function agentRunAdmissionDenial(
       });
       if (!decision.allowed) return "insufficient_credits";
     } else {
-      const balance = await getBillingBalance(services.db, input.accountId);
+      const balance = await getSpendableCreditBalance(
+        services.db,
+        input.accountId,
+        canonicalizeConfiguredModelId(services.settings, input.model),
+      );
       if (balance.balanceMicros <= 0) return "insufficient_credits";
     }
   }

package/src/billing/limits.ts

@@ -1,5 +1,6 @@
 import {
   configuredStaticUsageLimits,
+  canonicalizeConfiguredModelId,
   resolveModelProviderForTurn,
   type Settings,
 } from "@opengeni/config";
@@ -16,7 +17,7 @@ import {
   countActiveOrganizationApiKeysForAccount,
   countScheduledTasksForWorkspace,
   countWorkspacesForAccount,
-  getBillingBalance,
+  getSpendableCreditBalance,
   isCodexBilledTurn,
   recordUsageEvent,
   sumUsageQuantity,
@@ -148,11 +149,21 @@ async function checkCreditBalance(
   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(

package/src/default-session-model.ts

@@ -13,6 +13,7 @@ import {
   type WorkspaceSessionDefaults,
   type XaiProviderAccountAuthoritySnapshotV1,
   type ClaudeProviderAccountAuthoritySnapshotV1,
+  type BillingBalance,
 } from "@opengeni/contracts";
 import {
   getScheduledTaskXaiProviderAccountAuthoritySnapshot,
@@ -30,7 +31,8 @@ import {
   workspaceCodexSubscriptionActive,
   workspaceOpenRouterConnectionActive,
   workspaceVercelAiGatewayConnectionActive,
-  organizationHoldsCredits,
+  getBillingBalance,
+  spendableCreditMicros,
   workspaceXaiSubscriptionActive,
   workspaceXaiSubscriptionActiveForAuthority,
   XaiAuthorityPoolInactiveError,
@@ -112,16 +114,22 @@ export type DefaultSessionModelInput = {
    * `organizationHoldsCredits`).
    */
   creditsAvailable: boolean;
+  creditBalance?: BillingBalance;
 };
 
 function creditsCandidate(
-  input: Pick<DefaultSessionModelInput, "settings" | "selections">,
+  input: Pick<DefaultSessionModelInput, "settings" | "selections" | "creditBalance">,
 ): DefaultModelSelection | null {
+  const selections = input.creditBalance
+    ? input.selections.filter(
+        (selection) => spendableCreditMicros(input.creditBalance!, selection.model.id) > 0,
+      )
+    : input.selections;
   const fallbackEffort = input.settings.openaiReasoningEffort;
-  const deployment = findSelection(input.selections, input.settings.openaiModel);
-  const configured = findSelection(input.selections, input.settings.creditsDefaultModel);
+  const deployment = findSelection(selections, input.settings.openaiModel);
+  const configured = findSelection(selections, input.settings.creditsDefaultModel);
   if (deployment?.availability.selectable && deployment.model.cost === "credits") {
-    // An operator's paid deployment default is never replaced. When it is the
+    // A funded paid deployment default is preserved. When it is the
     // credits default model itself, credit holders get the credits default
     // effort rather than the deployment-wide fallback effort.
     if (configured?.model.id !== deployment.model.id) return null;
@@ -146,7 +154,7 @@ function creditsCandidate(
       source: "credits",
     };
   }
-  const first = input.selections.find(
+  const first = selections.find(
     (selection) => selection.availability.selectable && selection.model.cost === "credits",
   );
   return first
@@ -175,8 +183,8 @@ function creditsCandidate(
  *    configured credits default (`OPENGENI_CREDITS_DEFAULT_MODEL`, effort
  *    clamped to what the model supports), or the first selectable
  *    credits-billed model when that one is not selectable. When the
- *    deployment default is already a selectable credits-billed model it is
- *    never replaced: it keeps the deployment effort, except that it takes the
+ *    deployment default is already a funded, selectable credits-billed model it
+ *    keeps the deployment effort, except that it takes the
  *    credits default effort when it is the credits default model itself.
  * 4. `deployment`: the deployment default with the deployment reasoning effort
  *    when stably admissible; otherwise the first stably admissible catalog
@@ -247,6 +255,7 @@ export function creditsDefaultSessionModel(input: {
   settings: Settings;
   selections: readonly WorkspaceModelSelection[];
   workspaceSettings: unknown;
+  creditBalance?: BillingBalance;
 }): DefaultModelSelection | null {
   if (input.settings.billingMode !== "stripe") return null;
   return selectDefaultSessionModel({
@@ -254,6 +263,7 @@ export function creditsDefaultSessionModel(input: {
     selections: input.selections,
     workspaceDefaults: resolveWorkspaceSessionDefaults(input.workspaceSettings),
     creditsAvailable: true,
+    ...(input.creditBalance ? { creditBalance: input.creditBalance } : {}),
   });
 }
 
@@ -279,13 +289,14 @@ export async function resolveDefaultSessionModelForSelections(
   if (
     withoutCredits.source !== "deployment" ||
     input.settings.billingMode !== "stripe" ||
-    creditsCandidate(decision) === null
+    !input.selections.some(
+      (selection) => selection.availability.selectable && selection.model.cost === "credits",
+    )
   ) {
     return withoutCredits;
   }
-  return (await organizationHoldsCredits(db, input.accountId))
-    ? selectDefaultSessionModel({ ...decision, creditsAvailable: true })
-    : withoutCredits;
+  const creditBalance = await getBillingBalance(db, input.accountId);
+  return selectDefaultSessionModel({ ...decision, creditsAvailable: true, creditBalance });
 }
 
 export type WorkspaceModelSelectionContext = {

package/src/domain/knowledge-search.test.ts

@@ -40,7 +40,7 @@ const usage = mock(
 );
 mock.module("@opengeni/db", () => ({
   listKnowledgeEntries: list,
-  getBillingBalance: async () => ({ balanceMicros: balance }),
+  getSpendableCreditBalance: async () => ({ balanceMicros: balance }),
   applyCreditDebitAfterUse: debits,
   checkWorkspaceAllowance: allowanceChecks,
   creditDebitAttributionForTurn: async (_db: unknown, input: { turnId: string }) => ({

package/src/domain/knowledge-search.ts

@@ -4,7 +4,7 @@ import {
   applyCreditDebitAfterUse,
   checkWorkspaceAllowance,
   creditDebitAttributionForTurn,
-  getBillingBalance,
+  getSpendableCreditBalance,
   listKnowledgeEntries,
   recordUsageEvent,
   sumUsageQuantity,
@@ -190,7 +190,7 @@ export async function searchKnowledgeEntries(
     context.accountId,
     context.workspaceId,
     async (lockedDb) => {
-      const balance = await getBillingBalance(lockedDb, context.accountId);
+      const balance = await getSpendableCreditBalance(lockedDb, context.accountId);
       if (balance.balanceMicros <= 0)
         return keywordFallback(lockedDb, new KnowledgeVectorFundingError(), "awaiting_funding");
       const attribution =