@opengeni/api-router 1.3.0 → 1.4.2

package/dist/codemode.d.ts

@@ -1,7 +1,7 @@
 import { type AccessGrant, type AttemptToolCatalog, type CodemodeCallSubmission as CodemodeCallSubmissionValue, type CodemodeOperation } from "@opengeni/contracts";
 import type { ApiRouteDeps } from "@opengeni/core";
 import { type SessionTurnForExecution } from "@opengeni/db";
-import { type Settings } from "@opengeni/config";
+import { type FirstPartyMcpToolPolicySettings } from "@opengeni/config";
 import { type Permission, type Session } from "@opengeni/contracts";
 /** The REST authority a Codemode SDK proxy token may ever carry. */
 export declare const CODEMODE_SESSION_PROXY_PERMISSION_CEILING: readonly ["workspace:read", "sessions:read", "sessions:create", "sessions:control"];
@@ -13,10 +13,10 @@ export declare const CODEMODE_SESSION_PROXY_PERMISSION_CEILING: readonly ["works
  * gets only workspace:read and every proxied /sessions handler refuses it,
  * exactly as its MCP surface would.
  */
-export declare function codemodeSessionProxyPermissions(settings: Pick<Settings, "defaultFirstPartyMcpTools" | "allowedFirstPartyMcpTools">, session: Pick<Session, "firstPartyMcpTools" | "firstPartyMcpPermissions">): Permission[];
+export declare function codemodeSessionProxyPermissions(settings: FirstPartyMcpToolPolicySettings, session: Pick<Session, "firstPartyMcpTools" | "firstPartyMcpPermissions">): Permission[];
 /** Reuse normal REST handlers, including their resource/command authorization.
  * The exact attempt is checked before issuing this internal-only credential. */
-export declare function codemodeSessionRequest(deps: ApiRouteDeps, grant: AccessGrant, request: Request, path: string, resolveProxySettings?: (session: Session) => Pick<Settings, "defaultFirstPartyMcpTools" | "allowedFirstPartyMcpTools">): Promise<Request>;
+export declare function codemodeSessionRequest(deps: ApiRouteDeps, grant: AccessGrant, request: Request, path: string, resolveProxySettings?: (session: Session) => FirstPartyMcpToolPolicySettings): Promise<Request>;
 export type CodemodeGrantAuthority = {
     accountId: string;
     workspaceId: string;

package/dist/http/api-error.d.ts

@@ -37,6 +37,20 @@ export declare const DATABASE_UNAVAILABLE_ERROR_DETAIL_CODE = "DATABASE_UNAVAILA
  * must reconcile by its own idempotency key before resending.
  */
 export declare function databaseUnavailableHttpError(error: unknown, method: string): ApiHttpError | null;
+/** `details.code` of the retryable 503 for a deadlock/serialization victim. */
+export declare const DATABASE_CONTENTION_ERROR_DETAIL_CODE = "DATABASE_CONTENTION";
+/**
+ * PostgreSQL aborted the request's transaction as a deadlock (40P01) or
+ * serialization (40001) victim after any in-process retry was exhausted. The
+ * aborted transaction committed nothing, so this is transient contention, not
+ * an internal error. A read is safe to repeat. For a mutation the default is
+ * `outcomeUnknown` because an earlier transaction of the same request may have
+ * committed; a route whose only write is the aborted idempotent transaction
+ * passes `outcomeUnknown: false`.
+ */
+export declare function databaseContentionHttpError(error: unknown, method: string, options?: {
+    outcomeUnknown?: boolean;
+}): ApiHttpError | null;
 /**
  * A typed agent-configuration failure (capability unavailable, conflict,
  * widening, not enabled). Rendered as 422 validation_failed with the specific

package/dist/index.js

@@ -12,7 +12,7 @@ import {
   startSlackInteractionPump,
   startTemporalScheduleCleanupPump,
   withAccessGrantSessionRlsContext
-} from "./chunk-IZEGLLKZ.js";
+} from "./chunk-F3LQ6VWR.js";
 import "./chunk-OGQDXVXY.js";
 
 // src/index.ts

package/dist/integrations/oauth-profiles.d.ts

@@ -130,7 +130,9 @@ export type OAuthProviderProfile = {
         /** Distinguish a rejected OAuth grant from a temporary verification failure. */
         isRejectedGrant?: (payload: Record<string, unknown>) => boolean;
         validateIdentity: (payload: Record<string, unknown>) => Record<string, string>;
-        toolsForScopes: (scopes: readonly string[]) => Array<{
+        toolsForScopes: (scopes: readonly string[], deployment: {
+            gmailWatchTopicName?: string | undefined;
+        }) => Array<{
             name: string;
             description?: string;
         }>;

package/dist/routes/sessions.d.ts

@@ -1,11 +1,13 @@
 import { ClientSessionEvent, SessionScopeSubjectId, SteerSessionMessageRequest, type SessionStatus, type WorkClaimSubjectFilter, type SessionGoalRevision, type SessionAuthorizationOperation } from "@opengeni/contracts";
 import { decodeSessionListCursor, type SessionDiscoveryCursor } from "@opengeni/db";
 import type { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
 import type { ApiRouteDeps } from "@opengeni/core";
 import { type ViewerServices } from "../sandbox/viewer.js";
 type SessionRouteDeps = ApiRouteDeps & Pick<ViewerServices, "establishSandboxSession">;
 export declare function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void;
 export declare function goalProposalMatchesExpectedRevision(revision: Pick<SessionGoalRevision, "baseObjectiveRevision">, expectedObjectiveRevision: number): boolean;
+export declare function sessionRealtimeHttpError(error: unknown): HTTPException;
 /**
  * Map every mounted session-addressed HTTP path to the host-neutral operation
  * the embedding port authorizes. Returning null is deliberately fail-closed in

package/dist/transcription/billing-refusal.d.ts

@@ -0,0 +1,8 @@
+import type { TranscriptionBillingRefusedError } from "@opengeni/core";
+import type { Context } from "hono";
+/**
+ * Same body shape as session admission refusals (`code` + `message`, plus
+ * allowance `scope`/`resetsAt`), so SDK/React clients classify it as a
+ * definitive credit/allowance refusal rather than a retryable failure.
+ */
+export declare function transcriptionBillingRefusal(c: Context, error: TranscriptionBillingRefusedError): Response;

package/dist/transcription/normalize.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Decode one uploaded recording to 16 kHz mono PCM WAV with a hard decode
+ * ceiling, and measure its duration from the bytes the server produced.
+ */
+export type TranscriptionAudioNormalizer = (input: {
+    audio: Uint8Array;
+    mimeType: string;
+    /** Longest accepted recording; anything longer is refused, never truncated. */
+    maxDurationSeconds: number;
+    signal?: AbortSignal | undefined;
+}) => Promise<{
+    bytes: Uint8Array;
+    durationSeconds: number;
+}>;
+/**
+ * ffmpeg decodes at most `maxDurationSeconds + 1` seconds (`-t`), so a long or
+ * hostile upload costs bounded CPU and disk. Output that reaches that ceiling
+ * was longer than the limit and is refused as `too_large` before any provider
+ * call, so the transcript the user receives is never silently cut short.
+ */
+export declare function createFfmpegAudioNormalizer(input: {
+    ffmpegPath: string;
+}): TranscriptionAudioNormalizer;

package/dist/transcription/providers/azure-mai.d.ts

@@ -0,0 +1,12 @@
+import type { VoiceInputPricing } from "@opengeni/config";
+import type { TranscriptionProvider } from "@opengeni/core";
+/** Azure Speech file transcription; credentials and model selection stay server-side. */
+export declare function createMaiTranscriptionProvider(input: {
+    endpoint: string;
+    apiKey: string;
+    apiVersion: string;
+    model: string;
+    pricing?: VoiceInputPricing | null;
+    ffmpegPath: string;
+    fetch?: typeof fetch;
+}): TranscriptionProvider;

package/dist/transcription/providers/azure-openai.d.ts

@@ -1,3 +1,4 @@
+import { type VoiceInputPricing } from "@opengeni/config";
 import type { TranscriptionProvider } from "@opengeni/core";
 export declare function createAzureOpenAiTranscriptionProvider(input: {
     endpoint: string;
@@ -5,5 +6,8 @@ export declare function createAzureOpenAiTranscriptionProvider(input: {
     apiVersion: string;
     apiKey: string | null;
     adToken: string | null;
+    /** Underlying model of the deployment; defaults to the deployment name. */
+    model?: string;
+    pricing?: VoiceInputPricing | null;
     fetch?: typeof fetch;
 }): TranscriptionProvider;

package/dist/transcription/providers/openai.d.ts

@@ -1,9 +1,25 @@
+import { type VoiceInputPricing, type VoiceInputUsage } from "@opengeni/config";
 import { type TranscriptionProvider, TranscriptionServiceError } from "@opengeni/core";
 export declare function createOpenAiTranscriptionProvider(input: {
     apiKey: string;
     baseUrl: string;
     model: string;
+    pricing?: VoiceInputPricing | null;
     fetch?: typeof fetch;
 }): TranscriptionProvider;
+/**
+ * OpenAI-compatible `/audio/transcriptions` JSON (OpenAI and Azure OpenAI).
+ * `usage` is `{type:"tokens", input_tokens, input_token_details:{audio_tokens,
+ * text_tokens}, output_tokens, total_tokens}` for the gpt-4o-transcribe family
+ * or `{type:"duration", seconds}` for duration-billed models; Whisper
+ * `verbose_json` carries the processed audio `duration`. Unusable usage is
+ * dropped (null), never guessed.
+ */
+export declare function parseTranscriptionResponseBody(body: unknown): {
+    text: string;
+    languages: string[];
+    usage: VoiceInputUsage | null;
+} | null;
+export declare function parseTranscriptionUsage(body: Record<string, unknown>): VoiceInputUsage | null;
 export declare function responseError(status: number): TranscriptionServiceError;
 export declare function fetchError(error: unknown): TranscriptionServiceError;

package/dist/transcription/service.d.ts

@@ -1,6 +1,7 @@
 import { type Settings } from "@opengeni/config";
-import { type TranscriptionAvailabilityContext, type TranscriptionProvider, type TranscriptionService } from "@opengeni/core";
+import { type TranscriptionAvailabilityContext, type TranscriptionBilling, type TranscriptionProvider, type TranscriptionService } from "@opengeni/core";
 import type { Database } from "@opengeni/db";
+import { type TranscriptionAudioNormalizer } from "./normalize.js";
 export declare function createTranscriptionService(input: {
     settings: Settings;
     db: Database;
@@ -11,6 +12,14 @@ export declare function createTranscriptionService(input: {
     providerRequestTimeoutMilliseconds?: number;
     /** Test seam for evaluating persisted absolute deadlines after delayed setup. */
     now?: () => Date;
+    /** Credit admission/settlement for deployment-funded providers. */
+    billing?: TranscriptionBilling;
+    /** Test seam: trusted one-shot decode + duration (defaults to ffmpeg). */
+    normalizeAudio?: TranscriptionAudioNormalizer;
+    /** Loud operator log for settlement failures after provider success. */
+    log?: (message: string, attributes: Record<string, string | number | boolean>) => void;
+    /** In-process settlement retry pacing after an inline failure. */
+    settlementRetryDelaysMilliseconds?: readonly number[];
 }): TranscriptionService;
 export declare function remainingTranscriptionProviderRequestMilliseconds(providerDeadlineAt: Date, now: Date): number;
 export declare function orderedProviders(providers: readonly TranscriptionProvider[], context: TranscriptionAvailabilityContext): TranscriptionProvider[];

package/dist/transcription/wav-duration.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Duration of a PCM RIFF/WAVE buffer the server itself produced (resumable
+ * provider segments are ffmpeg-normalized WAV). Used only as the trusted
+ * billing fallback when a provider reports no usage; never applied to
+ * client-uploaded bytes. Returns null for anything that is not a well-formed
+ * WAV with a positive byte rate.
+ */
+export declare function wavDurationSeconds(bytes: Uint8Array): number | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/api-router",
-  "version": "1.3.0",
+  "version": "1.4.2",
   "description": "OpenGeni HTTP surface: the Hono adapter/router (createApp), routes, MCP HTTP transport, and HTTP access adapters over @opengeni/core. An engine-distribution surface — its runtime closure includes engine-internal packages.",
   "license": "Apache-2.0",
   "repository": {
@@ -43,25 +43,25 @@
     "@hono/zod-validator": "^0.7.6",
     "@llamaindex/liteparse": "2.14.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opengeni/agent-proto": "1.3.0",
-    "@opengeni/artifact-tool": "1.3.0",
-    "@opengeni/capabilities": "1.3.0",
-    "@opengeni/codemode": "1.3.0",
-    "@opengeni/codex": "1.3.0",
-    "@opengeni/config": "1.3.0",
-    "@opengeni/contracts": "1.3.0",
-    "@opengeni/core": "1.3.0",
-    "@opengeni/db": "1.3.0",
-    "@opengeni/documents": "1.3.0",
-    "@opengeni/events": "1.3.0",
-    "@opengeni/github": "1.3.0",
-    "@opengeni/interaction": "1.3.0",
-    "@opengeni/network": "1.3.0",
-    "@opengeni/observability": "1.3.0",
-    "@opengeni/runtime": "1.3.0",
-    "@opengeni/storage": "1.3.0",
-    "@opengeni/tool-gateway": "1.3.0",
-    "@opengeni/xai-subscription": "1.3.0",
+    "@opengeni/agent-proto": "1.4.2",
+    "@opengeni/artifact-tool": "1.4.2",
+    "@opengeni/capabilities": "1.4.2",
+    "@opengeni/codemode": "1.4.2",
+    "@opengeni/codex": "1.4.2",
+    "@opengeni/config": "1.4.2",
+    "@opengeni/contracts": "1.4.2",
+    "@opengeni/core": "1.4.2",
+    "@opengeni/db": "1.4.2",
+    "@opengeni/documents": "1.4.2",
+    "@opengeni/events": "1.4.2",
+    "@opengeni/github": "1.4.2",
+    "@opengeni/interaction": "1.4.2",
+    "@opengeni/network": "1.4.2",
+    "@opengeni/observability": "1.4.2",
+    "@opengeni/runtime": "1.4.2",
+    "@opengeni/storage": "1.4.2",
+    "@opengeni/tool-gateway": "1.4.2",
+    "@opengeni/xai-subscription": "1.4.2",
     "@temporalio/client": "^1.17.0",
     "better-auth": "^1.6.14",
     "hono": "^4.12.18",

package/src/access-grant-rls.ts

@@ -8,25 +8,33 @@ import {
   freezeAgentLearningPolicy,
   withSessionRlsActorContext,
   withCreditDebitAttribution,
+  type CreditDebitAttribution,
+  currentCreditDebitAttribution,
 } from "@opengeni/db";
 import { HTTPException } from "hono/http-exception";
 
+/**
+ * Trusted payer for a non-agent grant: an authenticated human session pays as
+ * that human; keys and services are service work. An agent attempt must be
+ * resolved through the validated middleware context installed below.
+ */
+export function creditDebitAttributionForGrant(grant: AccessGrant): CreditDebitAttribution {
+  if (grant.principalKind === "agent_attempt") return currentCreditDebitAttribution();
+  return grant.principalKind === "human_session"
+    ? { kind: "human", initiatingHumanSubjectId: grant.subjectId }
+    : ["service", "api_key", "configured_key", "mcp_gateway"].includes(grant.principalKind ?? "")
+      ? { kind: "service" }
+      : { kind: "unknown" };
+}
+
 export async function withAccessGrantSessionRlsContext<T>(
   deps: Pick<ApiRouteDeps, "db">,
   grant: AccessGrant,
   fn: () => Promise<T>,
 ): Promise<T> {
   if (grant.principalKind !== "agent_attempt") {
-    return await withCreditDebitAttribution(
-      grant.principalKind === "human_session"
-        ? { kind: "human", initiatingHumanSubjectId: grant.subjectId }
-        : grant.principalKind === "service" ||
-            grant.principalKind === "api_key" ||
-            grant.principalKind === "configured_key" ||
-            grant.principalKind === "mcp_gateway"
-          ? { kind: "service" }
-          : { kind: "unknown" },
-      () => withSessionRlsActorContext({ subjectId: grant.subjectId }, fn),
+    return await withCreditDebitAttribution(creditDebitAttributionForGrant(grant), () =>
+      withSessionRlsActorContext({ subjectId: grant.subjectId }, fn),
     );
   }
   const callerSessionId = grant.metadata?.sessionId;

package/src/app.ts

@@ -24,9 +24,10 @@ import {
   canonicalPublicOrigin,
   configuredAllowedReasoningEfforts,
   resolveFirstPartyMcpToolPolicy,
-  resolveVoiceInputProviderRegistry,
   UnsupportedLatencyModeError,
+  voiceInputPricingIssues,
   type Settings,
+  type FirstPartyMcpToolPolicySettings,
 } from "@opengeni/config";
 import {
   AGENT_CAPABILITY_IDS,
@@ -40,6 +41,7 @@ import {
   resolveWorkspaceMemoryEnabled,
   resolveWorkspaceMemoryPromptMode,
   VOICE_INPUT_ACCEPTED_MIME_TYPES,
+  WorkspaceVoiceInputSettings,
   TRANSCRIPTION_RECORDING_PROVIDER_SEGMENT_SECONDS,
   ToolGatewayApprovalRequest,
   ToolGatewayCallRequest,
@@ -97,7 +99,9 @@ import {
   ApiHttpError,
   agentConfigHttpError,
   allowanceExhaustedHttpError,
+  DATABASE_CONTENTION_ERROR_DETAIL_CODE,
   DATABASE_UNAVAILABLE_ERROR_DETAIL_CODE,
+  databaseContentionHttpError,
   databaseUnavailableHttpError,
   modelUnavailableHttpError,
   scheduledTaskTargetAccessHttpError,
@@ -491,12 +495,27 @@ export function createAppComposition(deps: AppDependencies): {
     }, MANAGED_AUTH_REAPER_INTERVAL_MS);
     (timer as ReturnType<typeof setInterval> & { unref?: () => void }).unref?.();
   }
+  if (deps.transcription === undefined) {
+    // Voice pricing problems never fail boot (workers share this config); the
+    // affected provider is withheld and the operator sees exactly why, once.
+    for (const issue of voiceInputPricingIssues(deps.settings)) {
+      observability.error(
+        `Voice input provider ${issue.providerId} is unavailable: ${issue.message}`,
+        {
+          providerId: issue.providerId,
+          env: issue.env,
+          reason: issue.reason,
+        },
+      );
+    }
+  }
   const transcription =
     deps.transcription === undefined
       ? createTranscriptionService({
           settings: deps.settings,
           db: deps.db,
           ...(deps.codexFetch ? { codexFetch: deps.codexFetch } : {}),
+          log: (message, attributes) => observability.error(message, attributes),
         })
       : deps.transcription;
   const transcriptionSegmenter =
@@ -644,8 +663,14 @@ export function createAppComposition(deps: AppDependencies): {
       "X-OpenGeni-Access-Key",
       "X-OpenGeni-Api-Contract",
       "X-OpenGeni-Actor-Epoch",
+      // Resumable voice-input chunk integrity/timing (cross-origin embeds).
+      "X-OpenGeni-Chunk-Duration-Milliseconds",
+      "X-OpenGeni-Chunk-Sha256",
+      "X-OpenGeni-Chunk-Start-Milliseconds",
       "X-OpenGeni-Correlation-Id",
       "X-OpenGeni-Session-Csrf",
+      // Session scope for a session proxy; the API itself ignores it.
+      "X-OpenGeni-Session-Id",
       "X-OpenGeni-Site-Id",
       "X-OpenGeni-Site-Version",
       "X-OpenGeni-Subject",
@@ -1191,6 +1216,8 @@ export function createAppComposition(deps: AppDependencies): {
       creditsAvailable: false,
     });
     let modelSelectionForbidden = false;
+    let voiceInputAvailable = false;
+    let voiceInputProviders: string[] = [];
     const requestedWorkspaceId = c.req.query("workspaceId");
     if (requestedWorkspaceId !== undefined && requestedWorkspaceId.trim() === "") {
       throw new HTTPException(422, { message: "workspaceId must not be empty" });
@@ -1241,6 +1268,25 @@ export function createAppComposition(deps: AppDependencies): {
             selections = [];
           }
           const workspace = await getWorkspace(deps.db, workspaceId);
+          const voicePreferences = WorkspaceVoiceInputSettings.safeParse(
+            workspace?.settings.voiceInput,
+          ).data;
+          const voiceContext = {
+            workspaceId,
+            subjectId: grant.subjectId,
+            preferredProvider: voicePreferences?.preferredProvider,
+            fallbackEnabled: voicePreferences?.fallbackEnabled,
+          };
+          if (hasPermission(grant.permissions, "sessions:create") && transcription) {
+            // `providers` lists every ready provider (the workspace picker);
+            // `available` honours the workspace preference and fallback, so
+            // the composer never offers a mic every request would refuse.
+            voiceInputProviders = (await transcription.availableProviderIds?.(voiceContext)) ?? [];
+            voiceInputAvailable =
+              voiceInputProviders.length > 0 &&
+              (await Promise.resolve(transcription.available(voiceContext)).catch(() => false));
+          }
+
           defaultSelection = await resolveDefaultSessionModelForSelections(deps.db, {
             settings: catalogSettings,
             accountId: grant.accountId,
@@ -1303,10 +1349,8 @@ export function createAppComposition(deps: AppDependencies): {
           maxSizeBytes: objectStorage?.maxSinglePutSizeBytes ?? 5_000_000_000,
         },
         voiceInput: {
-          providers: resolveVoiceInputProviderRegistry(deps.settings).map(
-            (provider) => provider.id,
-          ),
-          available: (await transcription?.available()) ?? false,
+          providers: voiceInputProviders,
+          available: voiceInputAvailable,
           maxDurationSeconds: deps.settings.voiceInputMaxDurationSeconds,
           maxSizeBytes: deps.settings.voiceInputMaxSizeBytes,
           acceptedMimeTypes: [...VOICE_INPUT_ACCEPTED_MIME_TYPES],
@@ -1314,7 +1358,7 @@ export function createAppComposition(deps: AppDependencies): {
           objectStorage &&
           transcription &&
           transcriptionSegmenter &&
-          (await transcription.available()) &&
+          voiceInputAvailable &&
           (await transcriptionSegmenter.available())
             ? {
                 resumable: {
@@ -1920,6 +1964,7 @@ export function createAppComposition(deps: AppDependencies): {
           requestBodyValidationHttpError(rawError) ??
           invalidPathIdentifierHttpError(rawError, new URL(c.req.url).pathname) ??
           databaseUnavailableHttpError(rawError, c.req.method) ??
+          databaseContentionHttpError(rawError, c.req.method) ??
           rawError);
     const compactionLock = codexCompactionV2ProviderLockedError(error);
     const apiError = error instanceof ApiHttpError ? error : null;
@@ -1928,7 +1973,10 @@ export function createAppComposition(deps: AppDependencies): {
       ? compactionLock.code
       : (apiError?.code ?? errorCodeForStatus(status));
     if (status >= 500) logHttpFailure(c, status, code, rawError);
-    if (apiError?.details?.code === DATABASE_UNAVAILABLE_ERROR_DETAIL_CODE) {
+    if (
+      apiError?.details?.code === DATABASE_UNAVAILABLE_ERROR_DETAIL_CODE ||
+      apiError?.details?.code === DATABASE_CONTENTION_ERROR_DETAIL_CODE
+    ) {
       c.header("retry-after", "1");
     }
     const envelope = ErrorEnvelope.parse({
@@ -2107,7 +2155,7 @@ function clientAuthConfig(settings: AppDependencies["settings"], newSignupsEnabl
 
 /** Configured SDK credentials cannot regain tools from widened legacy columns. */
 export function configuredCodemodeSessionProxyTools(
-  settings: Pick<Settings, "defaultFirstPartyMcpTools" | "allowedFirstPartyMcpTools">,
+  settings: FirstPartyMcpToolPolicySettings,
   session: Pick<Session, "agent">,
 ): FirstPartyMcpToolName[] | null {
   if (!session.agent) return null;
@@ -2236,6 +2284,12 @@ export function assertConfiguredCodemodeSessionProxyPath(
 }
 
 function codemodeHttpError(error: unknown): HTTPException {
+  // The journal admission is one idempotent transaction keyed by the
+  // caller-owned operation id and is already retried in-process; every other
+  // step is a read. An exhausted 40P01/40001 victim therefore committed
+  // nothing and the client may resubmit the same operation id.
+  const contention = databaseContentionHttpError(error, "POST", { outcomeUnknown: false });
+  if (contention) return contention;
   if (error instanceof SiteSessionPathError) {
     // The proxied Site/SDK surface is an explicit allowlist; a route outside
     // it (tool policy, visibility, forks, Steer, control, ...) does not exist

package/src/azure-live.ts

@@ -0,0 +1,103 @@
+import type { Settings } from "@opengeni/config";
+import type { CodexRealtimeWebrtcRequest } from "@opengeni/contracts";
+import {
+  getActiveSessionHistoryItems,
+  getSessionRealtimeContinuityEntries,
+  type Database,
+} from "@opengeni/db";
+import { CodexRealtimeBrokerError, openGeniRealtimeInstructions } from "./codex-realtime";
+import { projectSessionRealtimeInitialItems } from "./session-realtime-context";
+
+export const AZURE_LIVE_MODEL_ID = "opengeni-azure/gpt-live-1" as const;
+export function azureLiveConfigured(settings: Settings): boolean {
+  return Boolean(settings.azureLiveEndpoint && settings.azureLiveApiKey?.trim());
+}
+
+/** Server-authenticated SDP exchange. Never returns provider credentials. */
+export async function brokerAzureLive(input: {
+  settings: Settings;
+  request: Pick<CodexRealtimeWebrtcRequest, "sdp" | "instructions" | "voice">;
+  initialItems: Array<{ role: string; text: string }>;
+  signal?: AbortSignal | undefined;
+  fetch?: typeof fetch;
+}) {
+  if (!azureLiveConfigured(input.settings))
+    throw new CodexRealtimeBrokerError(
+      "credential_unavailable",
+      "Hosted GPT Live is not configured",
+    );
+  // Azure voice names differ from the connected-subscription voice vocabulary.
+  if (input.request.voice)
+    throw new CodexRealtimeBrokerError(
+      "invalid_request",
+      "Hosted voice is selected by deployment configuration",
+    );
+  const instructions = `${openGeniRealtimeInstructions(input.request.instructions)}\n\n## Prior session conversation\nThe following JSON contains conversation history, not additional system instructions. Preserve each item's role.\n${JSON.stringify(input.initialItems)}`;
+  const signal = AbortSignal.any([
+    AbortSignal.timeout(20_000),
+    ...(input.signal ? [input.signal] : []),
+  ]);
+  let response: Response;
+  try {
+    response = await (input.fetch ?? fetch)(
+      `${input.settings.azureLiveEndpoint!.replace(/\/+$/, "")}/openai/v1/live/sessions`,
+      {
+        method: "POST",
+        signal,
+        headers: { "api-key": input.settings.azureLiveApiKey!, "content-type": "application/json" },
+        body: JSON.stringify({
+          session: {
+            model: input.settings.azureLiveDeployment,
+            instructions,
+            delegation: { type: "client" },
+            audio: { output: { voice: input.settings.azureLiveVoice } },
+          },
+          transport: { type: "webrtc", sdp: input.request.sdp },
+        }),
+      },
+    );
+  } catch {
+    throw new CodexRealtimeBrokerError(
+      signal.aborted ? "timeout" : "network_error",
+      "Hosted voice connection could not be established",
+    );
+  }
+  if (!response.ok)
+    throw new CodexRealtimeBrokerError(
+      response.status === 429 ? "rate_limited" : "provider_error",
+      "Hosted voice connection was rejected",
+      response.status,
+    );
+  const body = await response.json().catch(() => null);
+  const sdp = body?.transport?.sdp;
+  if (typeof sdp !== "string" || !sdp || sdp.length > 1_048_576)
+    throw new CodexRealtimeBrokerError(
+      "invalid_provider_response",
+      "Hosted voice returned an invalid connection answer",
+    );
+  return { sdp, version: "v3" as const, model: AZURE_LIVE_MODEL_ID };
+}
+
+export function buildSessionAzureLiveBroker(
+  db: Database,
+  settings: Settings,
+  workspaceId: string,
+  sessionId: string,
+  fetchImpl?: typeof fetch,
+) {
+  return async (input: {
+    request: Pick<CodexRealtimeWebrtcRequest, "sdp" | "instructions" | "voice">;
+    signal?: AbortSignal | undefined;
+  }) => {
+    const [history, continuity] = await Promise.all([
+      getActiveSessionHistoryItems(db, workspaceId, sessionId),
+      getSessionRealtimeContinuityEntries(db, workspaceId, sessionId),
+    ]);
+    return brokerAzureLive({
+      settings,
+      ...input,
+      initialItems: projectSessionRealtimeInitialItems(history, continuity),
+      ...(fetchImpl ? { fetch: fetchImpl } : {}),
+    });
+  };
+}

package/src/codemode.ts

@@ -28,7 +28,7 @@ import { getSession } from "@opengeni/db";
 import {
   allowedFirstPartyMcpToolsForSession,
   resolveFirstPartyDelegationSecret,
-  type Settings,
+  type FirstPartyMcpToolPolicySettings,
 } from "@opengeni/config";
 import {
   DEFAULT_FIRST_PARTY_MCP_PERMISSIONS,
@@ -59,7 +59,7 @@ export const CODEMODE_SESSION_PROXY_PERMISSION_CEILING = [
  * exactly as its MCP surface would.
  */
 export function codemodeSessionProxyPermissions(
-  settings: Pick<Settings, "defaultFirstPartyMcpTools" | "allowedFirstPartyMcpTools">,
+  settings: FirstPartyMcpToolPolicySettings,
   session: Pick<Session, "firstPartyMcpTools" | "firstPartyMcpPermissions">,
 ): Permission[] {
   const sessionPermissions = session.firstPartyMcpPermissions ?? [
@@ -82,9 +82,7 @@ export async function codemodeSessionRequest(
   grant: AccessGrant,
   request: Request,
   path: string,
-  resolveProxySettings?: (
-    session: Session,
-  ) => Pick<Settings, "defaultFirstPartyMcpTools" | "allowedFirstPartyMcpTools">,
+  resolveProxySettings?: (session: Session) => FirstPartyMcpToolPolicySettings,
 ): Promise<Request> {
   siteSessionPath(path, grant.workspaceId, request.method);
   const { authority, turn } = await requireActiveCodemodeCatalog(deps, grant);

package/src/gateway-realtime.ts

@@ -72,6 +72,7 @@ export async function createGatewayRealtimeConnectionSecret(input: {
     getSessionRealtimeContinuityEntries(input.db, input.workspaceId, input.sessionId),
     mintGatewayClientSecret({
       apiKey,
+      source: resolved.source,
       upstreamModelId: resolved.upstreamModelId,
       fetchImpl: input.fetchImpl ?? fetch,
     }),
@@ -86,6 +87,7 @@ export async function createGatewayRealtimeConnectionSecret(input: {
 
 async function mintGatewayClientSecret(input: {
   apiKey: string;
+  source: "managed" | "workspace";
   upstreamModelId: string;
   fetchImpl: typeof fetch;
 }): Promise<{ token: string; url: string; expiresAt: number | null }> {
@@ -105,17 +107,19 @@ async function mintGatewayClientSecret(input: {
   } catch {
     throw new GatewayRealtimeBrokerError(
       "provider_error",
-      "AI Gateway realtime token request failed",
+      "The voice provider could not be reached. Try again.",
     );
   }
   if (!response.ok) {
+    const rejected = response.status === 401 || response.status === 403;
+    // User-facing: say what to do, never which deployment credential failed.
     throw new GatewayRealtimeBrokerError(
-      response.status === 401 || response.status === 403
-        ? "credential_unavailable"
-        : "provider_error",
-      response.status === 401 || response.status === 403
-        ? "AI Gateway credentials were rejected"
-        : "AI Gateway realtime token request failed",
+      rejected ? "credential_unavailable" : "provider_error",
+      rejected
+        ? input.source === "managed"
+          ? "Opengeni voice is temporarily unavailable. Try another voice model."
+          : "Your AI Gateway key was rejected. Update it in workspace settings."
+        : "The voice provider could not start a call. Try again.",
       response.status,
     );
   }