@opengeni/core 1.3.0 → 1.4.0

package/src/domain/session-connection-accounts.ts

@@ -1,5 +1,5 @@
 import type { AccessGrant } from "@opengeni/contracts";
-import type { Settings } from "@opengeni/config";
+import { allowedFirstPartyMcpToolsForSession, type Settings } from "@opengeni/config";
 import { requireSession, requireWorkspace, type Database } from "@opengeni/db";
 import { settingsWithEnabledCapabilityMcpServers } from "./capabilities";
 import {
@@ -44,6 +44,10 @@ export async function freezeSessionRealtimeConnectionAccounts(input: {
       (await requireWorkspace(db, workspaceId)).settings,
     ),
   });
+  const effectiveFirstPartyTools = allowedFirstPartyMcpToolsForSession(
+    settings,
+    session.firstPartyMcpTools,
+  );
   return await freezeConnectionAccounts({
     db,
     settings: runtimeSettings,
@@ -54,8 +58,8 @@ export async function freezeSessionRealtimeConnectionAccounts(input: {
     source: personalConnectionDelegationSourceForGrant(grant),
     targetSessionId: sessionId,
     googleDrivePublicationEnabled:
-      session.firstPartyMcpTools.includes("editable_artifact_export") &&
-      session.firstPartyMcpTools.includes("editable_artifact_export_status") &&
+      effectiveFirstPartyTools.includes("editable_artifact_export") &&
+      effectiveFirstPartyTools.includes("editable_artifact_export_status") &&
       (!session.firstPartyMcpPermissions?.length ||
         (session.firstPartyMcpPermissions.includes("artifacts:read") &&
           session.firstPartyMcpPermissions.includes("artifacts:publish"))),

package/src/domain/session-tool-policy.ts

@@ -3,6 +3,7 @@ import {
   codeSearchDeploymentPolicy,
   resolveModelProviderForTurn,
   resolveFirstPartyDelegationSecret,
+  webSearchToolPlan,
   type Settings,
 } from "@opengeni/config";
 import {
@@ -443,9 +444,18 @@ export function sessionEffectiveToolProjectionInput(
   const supportsImages =
     model?.model.api === "responses" && model.model.capabilities.inputModalities.includes("image");
   const hostedToolNames: AgentFunctionToolName[] = [];
+  // Same plan the worker applies: provider web_search/web_fetch where the
+  // model has no hosted search (or the operator chose `replace`).
+  const webSearchPlan = context
+    ? webSearchToolPlan(context.settings, {
+        hostedWebSearch: model?.model.hostedWebSearch ?? context.settings.webSearchEnabled,
+        transportHostedSearch: model?.provider.kind === "xai-subscription",
+      })
+    : { hostedWebSearch: false, providerTools: [] };
   if (model?.provider.kind === "xai-subscription") {
     if (context?.settings.webSearchEnabled) hostedToolNames.push("web_search", "x_search");
-  } else if (model?.model.hostedWebSearch) hostedToolNames.push("web_search");
+  } else if (model?.model.hostedWebSearch && webSearchPlan.hostedWebSearch)
+    hostedToolNames.push("web_search");
   const mediaAttachment =
     context?.mediaAttachments?.get(session.id) ??
     (context?.objectStorageAvailable === false
@@ -460,6 +470,7 @@ export function sessionEffectiveToolProjectionInput(
         "skill_read",
         ...AGENT_SKILL_MANAGE_TOOL_NAMES,
         ...media.runtime,
+        ...webSearchPlan.providerTools,
       ]
     : [];
   const sandboxToolNames: AgentFunctionToolName[] = sandboxAvailable
@@ -549,6 +560,7 @@ export function sessionEffectiveToolProjectionInput(
     "skill_read",
     "request_human_input",
     "list_models",
+    ...webSearchPlan.providerTools,
     ...(toolRefs.some((ref) => ref.id === "opengeni" && ref.eager === true) ||
     !progressiveDisclosure
       ? firstPartyMcpTools.filter((name) => !interactionNames.has(name) || !progressiveDisclosure)
@@ -563,7 +575,7 @@ export function sessionEffectiveToolProjectionInput(
         : []),
     ]),
     hasSkills: context ? sessionHasSkills(session, context) : false,
-    webSearch: hostedToolNames.includes("web_search"),
+    webSearch: hostedToolNames.includes("web_search") || webSearchPlan.providerTools.length > 0,
     humanInput: context?.humanInputEnabled ?? false,
     media: media.toolsKnown ? media.hosted.length + media.runtime.length > 0 : undefined,
     routerInHistory:

package/src/domain/sessions.ts

@@ -42,6 +42,7 @@ import {
   ORGANIZATION_GATEWAY_MODEL_ID_PREFIX,
   ORGANIZATION_OPENROUTER_MODEL_ID_PREFIX,
   allowedFirstPartyMcpToolsForSession,
+  deploymentUnavailableFirstPartyMcpTools,
   resolveFirstPartyMcpToolPolicy,
   policyProviderIdForModel,
   resolveTurnExecutionPolicyV1,
@@ -2410,6 +2411,14 @@ async function createSessionForRequestInFileScope(
   requestOptions: SessionCreateRequestOptions = {},
 ): Promise<CreateSessionRequestOutcome> {
   const payload = CreateSessionRequest.parse(rawPayload);
+  // A tool whose backing workload this deployment does not run is dropped, not
+  // rejected: a client echoing a full catalog must not fail on a deployment fact.
+  if (payload.firstPartyMcpTools) {
+    const unavailable = deploymentUnavailableFirstPartyMcpTools(unresolvedDeps.settings);
+    payload.firstPartyMcpTools = payload.firstPartyMcpTools.filter(
+      (tool) => !unavailable.has(tool),
+    );
+  }
   // Read before any await: the Site scope is request-local provenance.
   const surface = resolveTurnSurface({
     grant,
@@ -4249,6 +4258,10 @@ async function acceptSessionUserMessageInFileScope(
         (await requireWorkspace(db, workspaceId)).settings,
       ),
     });
+    const existingEffectiveFirstPartyTools = allowedFirstPartyMcpToolsForSession(
+      settings,
+      existingSession.firstPartyMcpTools,
+    );
     const { personalConnectionDelegations, mcpAccountBindings } = await freezeConnectionAccounts({
       db,
       accountId: grant.accountId,
@@ -4259,8 +4272,8 @@ async function acceptSessionUserMessageInFileScope(
       source: connectionDelegationSource,
       targetSessionId: sessionId,
       googleDrivePublicationEnabled:
-        existingSession.firstPartyMcpTools.includes("editable_artifact_export") &&
-        existingSession.firstPartyMcpTools.includes("editable_artifact_export_status") &&
+        existingEffectiveFirstPartyTools.includes("editable_artifact_export") &&
+        existingEffectiveFirstPartyTools.includes("editable_artifact_export_status") &&
         (!existingSession.firstPartyMcpPermissions?.length ||
           (existingSession.firstPartyMcpPermissions.includes("artifacts:read") &&
             existingSession.firstPartyMcpPermissions.includes("artifacts:publish"))),

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

@@ -0,0 +1,310 @@
+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,
+  type CreditDebitAttribution,
+  type Database,
+} from "@opengeni/db";
+import {
+  TranscriptionBillingRefusedError,
+  TranscriptionServiceError,
+  type TranscriptionBilling,
+  type TranscriptionBillingContext,
+} from "../transcription";
+
+/** 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: general
+ * (not model-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.",
+        });
+      }
+      // 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);
+      if (balance.balanceMicros <= 0) {
+        throw new TranscriptionBillingRefusedError({
+          code: "insufficient_credits",
+          message: "Voice input needs Opengeni credits. Add credits to continue.",
+        });
+      }
+      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,
+      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,
+      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,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