@opengeni/api-router 3.0.1 → 3.1.2

package/src/codemode.ts

@@ -1,4 +1,3 @@
-import { siteRequestHeaders } from "@opengeni/contracts/site-session-http";
 import {
   codemodeDispatchSubject,
   decodeCodemodeDispatchAck,
@@ -14,29 +13,43 @@ import {
   type CodemodeOperation,
 } from "@opengeni/contracts";
 import type { ApiRouteDeps } from "@opengeni/core";
-import { hasPermission, requireSessionAuthorization } from "@opengeni/core";
+import { hasPermission, isDeveloperSetupGrant, requireSessionAuthorization } from "@opengeni/core";
 import {
+  CodemodeToolApprovalRequiredError,
   getActiveSessionTurnForExecution,
   getAttemptToolCatalog,
   getCodemodeOperation,
+  readTurnCodemodeOperation,
   submitCodemodeOperation,
+  type SessionTurnForExecution,
 } from "@opengeni/db";
-import { getSession } from "@opengeni/db";
+import { getSession, requireWorkspace } from "@opengeni/db";
 import {
   allowedFirstPartyMcpToolsForSession,
+  resolveSessionFirstPartyMcpTools,
   resolveFirstPartyDelegationSecret,
-  type Settings,
+  type FirstPartyMcpToolPolicySettings,
 } from "@opengeni/config";
 import {
   DEFAULT_FIRST_PARTY_MCP_PERMISSIONS,
   signDelegatedAccessToken,
-  siteSessionPath,
+  readTurnExecutionPolicyV1,
   OPENGENI_API_CONTRACT_HEADER,
   OPENGENI_API_CONTRACT_REVISION,
   type Permission,
   type Session,
 } from "@opengeni/contracts";
+import {
+  SITE_FRAME_HEADER,
+  SITE_FRAME_ID_HEADER,
+  SITE_PREVIEW_FRAME,
+  siteFrameFromHeaders,
+  siteHostWorkspacePath,
+  siteRequestHeaders,
+  siteSessionPath,
+} from "@opengeni/contracts/site-session-http";
 import { permissionsRequiredByFirstPartyTools } from "./mcp/first-party-tool-permissions";
+import { isPreparedMcpConnectPath, preparedMcpProxyPermissions } from "./prepared-mcp-permissions";
 
 /** The REST authority a Codemode SDK proxy token may ever carry. */
 export const CODEMODE_SESSION_PROXY_PERMISSION_CEILING = [
@@ -55,7 +68,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 ?? [
@@ -71,6 +84,34 @@ export function codemodeSessionProxyPermissions(
   );
 }
 
+const FRAME_ID = /^[A-Za-z0-9_-]{1,64}$/u;
+
+/**
+ * The route a Codemode SDK proxy request may take. The agent's own SDK calls
+ * keep the workspace prefix boundary under the proxy permission ceiling. A
+ * request a local Site preview forwarded from page code carries the frame
+ * marker and is held to the `SITE_OPERATIONS` allowlist; it stays marked as
+ * a preview frame (never a published Site) so the API records its origin and
+ * keeps it to the sessions it started.
+ */
+function codemodeProxyRoute(request: Request, path: string) {
+  const frame = siteFrameFromHeaders((name) => request.headers.get(name));
+  if (!frame) {
+    return {
+      path: (workspaceId: string) => siteHostWorkspacePath(path, workspaceId),
+      frameHeaders: null,
+    };
+  }
+  const frameId = frame.frameId && FRAME_ID.test(frame.frameId) ? frame.frameId : null;
+  return {
+    path: (workspaceId: string) => siteSessionPath(path, workspaceId, request.method),
+    frameHeaders: {
+      [SITE_FRAME_HEADER]: SITE_PREVIEW_FRAME,
+      ...(frameId ? { [SITE_FRAME_ID_HEADER]: frameId } : {}),
+    },
+  };
+}
+
 /** Reuse normal REST handlers, including their resource/command authorization.
  * The exact attempt is checked before issuing this internal-only credential. */
 export async function codemodeSessionRequest(
@@ -78,23 +119,56 @@ export async function codemodeSessionRequest(
   grant: AccessGrant,
   request: Request,
   path: string,
+  resolveProxySettings?: (session: Session) => FirstPartyMcpToolPolicySettings,
 ): Promise<Request> {
-  siteSessionPath(path, grant.workspaceId, request.method);
-  const { authority } = await requireActiveCodemodeCatalog(deps, grant);
+  const route = codemodeProxyRoute(request, path);
+  route.path(grant.workspaceId);
+  const { authority, turn, catalog } = await requireActiveCodemodeCatalog(deps, grant);
   const session = await getSession(deps.db, authority.workspaceId, authority.sessionId);
   const secret = resolveFirstPartyDelegationSecret(deps.settings);
   if (!session || !secret) throw new CodemodeAuthorityError("invalid_grant");
-  const permissions = codemodeSessionProxyPermissions(deps.settings, session);
+  const selection = resolveSessionFirstPartyMcpTools(
+    resolveProxySettings?.(session) ?? deps.settings,
+    session,
+    (await requireWorkspace(deps.db, authority.workspaceId)).settings,
+  ).filter((name) =>
+    catalog.entries.some(
+      (entry) => entry.identity.serverId === "opengeni" && entry.identity.toolName === name,
+    ),
+  );
+  const permissions = codemodeSessionProxyPermissions(
+    resolveProxySettings?.(session) ?? deps.settings,
+    { ...session, firstPartyMcpTools: selection },
+  );
+  if (isPreparedMcpConnectPath(route.path(grant.workspaceId), request.method)) {
+    if (selection.includes("custom_mcp_setup_request"))
+      permissions.push(
+        ...preparedMcpProxyPermissions(
+          catalog,
+          session.firstPartyMcpPermissions ?? [...DEFAULT_FIRST_PARTY_MCP_PERMISSIONS],
+        ),
+      );
+  }
+  const turnPolicy = readTurnExecutionPolicyV1(turn.metadata);
+  const initialPolicy = readTurnExecutionPolicyV1(session.metadata);
+  const restricted =
+    isDeveloperSetupGrant(grant) ||
+    (turnPolicy.kind === "valid" &&
+      turnPolicy.policy.credentialRestriction === "developer_setup") ||
+    (initialPolicy.kind === "valid" &&
+      initialPolicy.policy.credentialRestriction === "developer_setup");
   const token = await signDelegatedAccessToken(secret, {
     ...authority,
     permissions,
     principalKind: "agent_attempt",
+    ...(restricted ? { credentialRestriction: "developer_setup" as const } : {}),
     exp: Math.floor(Date.now() / 1000) + 60,
   });
   const target = new URL(request.url);
-  const rewritten = siteSessionPath(path, authority.workspaceId, request.method);
+  const rewritten = route.path(authority.workspaceId);
   const url = new URL(rewritten, target.origin);
   const headers = siteRequestHeaders(request.headers);
+  for (const [name, value] of Object.entries(route.frameHeaders ?? {})) headers.set(name, value);
   headers.set("authorization", `Bearer ${token}`);
   headers.set(OPENGENI_API_CONTRACT_HEADER, OPENGENI_API_CONTRACT_REVISION);
   return new Request(url, {
@@ -206,7 +280,11 @@ export function requireMatchingCodemodeCatalog(
 export async function requireActiveCodemodeCatalog(
   deps: ApiRouteDeps,
   grant: AccessGrant,
-): Promise<{ authority: CodemodeGrantAuthority; catalog: AttemptToolCatalog }> {
+): Promise<{
+  authority: CodemodeGrantAuthority;
+  catalog: AttemptToolCatalog;
+  turn: SessionTurnForExecution;
+}> {
   if (!isCodemodeGrant(grant)) throw new CodemodeAuthorityError("invalid_grant");
   const authority = codemodeAuthorityForGrant(grant)!;
   await requireSessionAuthorization(deps, grant, {
@@ -236,19 +314,21 @@ export async function requireActiveCodemodeCatalog(
       attemptId: authority.attemptId,
     }),
   );
-  return { authority, catalog };
+  return { authority, catalog, turn: active };
 }
 
 export async function submitAndDispatchCodemodeCall(
   deps: ApiRouteDeps,
   grant: AccessGrant,
   rawRequest: unknown,
+  signal?: AbortSignal,
 ): Promise<CodemodeCallSubmissionValue> {
-  const request = CodemodeCallRequest.parse(rawRequest);
+  const { durableApproval, ...request } = CodemodeCallRequest.parse(rawRequest);
   const { authority, catalog } = await requireActiveCodemodeCatalog(deps, grant);
   if (request.catalogDigest !== catalog.digest) throw new CodemodeCatalogStaleError();
   const submitted = await submitCodemodeOperation(deps.db, {
     ...authority,
+    ...(durableApproval ? { durableApproval: true } : {}),
     call: {
       ...request,
       caller: { kind: "codemode", subjectId: authority.subjectId },
@@ -261,36 +341,149 @@ export async function submitAndDispatchCodemodeCall(
       ? "already_running"
       : "unavailable";
   if (codemodeOperationNeedsDispatch(operation)) {
-    try {
-      const reply = await deps.bus.request(
-        codemodeDispatchSubject(authority.workspaceId, authority.attemptId),
-        encodeCodemodeDispatchRequest({
-          version: 1,
-          operationId: operation.operationId,
-          catalogDigest: catalog.digest,
-        }),
-        { timeoutMs: CODEMODE_DISPATCH_TIMEOUT_MS },
-      );
-      dispatch = decodeCodemodeDispatchAck(reply.data).status;
-    } catch {
-      dispatch = "unavailable";
-    }
-    operation = await refreshAdmittedCodemodeOperation(operation, () =>
+    const readOperation = () =>
       getCodemodeOperation(deps.db, {
         accountId: authority.accountId,
         workspaceId: authority.workspaceId,
         attemptId: authority.attemptId,
         operationId: operation.operationId,
-      }),
-    );
-    if (terminal(operation)) dispatch = "terminal";
-    else if (operation.state === "running" && dispatch === "unavailable") {
-      dispatch = "already_running";
+      });
+    // Listen before dispatching so a fast settlement cannot be missed. The
+    // settlement event is committed with the operation row, so its arrival
+    // means one read returns the terminal operation.
+    const wake = codemodeSettlementWake();
+    const unsubscribe = await deps.bus
+      .subscribe(authority.workspaceId, authority.sessionId, (events) => {
+        if (events.some((event) => isCodemodeSettlementEvent(event, operation.operationId))) {
+          wake.notify();
+        }
+      })
+      .catch(() => null);
+    try {
+      try {
+        const reply = await deps.bus.request(
+          codemodeDispatchSubject(authority.workspaceId, authority.attemptId),
+          encodeCodemodeDispatchRequest({
+            version: 1,
+            operationId: operation.operationId,
+            catalogDigest: catalog.digest,
+          }),
+          { timeoutMs: CODEMODE_DISPATCH_TIMEOUT_MS },
+        );
+        dispatch = decodeCodemodeDispatchAck(reply.data).status;
+      } catch {
+        dispatch = "unavailable";
+      }
+      operation = await refreshAdmittedCodemodeOperation(operation, readOperation);
+      // An executing call usually settles within moments. Return its result in
+      // this response so clients need no polling round; a longer call returns
+      // still running and is read as before.
+      if (
+        unsubscribe &&
+        !terminal(operation) &&
+        (dispatch === "accepted" || dispatch === "already_running")
+      ) {
+        operation = await awaitCodemodeSettlement({
+          operation,
+          read: readOperation,
+          wake,
+          budgetMs: CODEMODE_SUBMIT_SETTLE_WAIT_MS,
+          fallbackReadMs: CODEMODE_SETTLE_FALLBACK_READ_MS,
+          ...(signal ? { signal } : {}),
+        });
+      }
+      if (terminal(operation)) dispatch = "terminal";
+      else if (operation.state === "running" && dispatch === "unavailable") {
+        dispatch = "already_running";
+      }
+    } finally {
+      unsubscribe?.();
     }
   }
   return CodemodeCallSubmission.parse({ operation, dispatch });
 }
 
+/**
+ * How long a submission holds its request open for the call to settle. Most
+ * tool calls finish well within it; a longer call returns still running.
+ */
+export const CODEMODE_SUBMIT_SETTLE_WAIT_MS = 8_000;
+/** Safety-net read cadence if the live settlement event is missed. */
+export const CODEMODE_SETTLE_FALLBACK_READ_MS = 400;
+
+export function isCodemodeSettlementEvent(
+  event: { type: string; payload?: unknown },
+  operationId: string,
+): boolean {
+  if (event.type !== "agent.toolCall.output") return false;
+  const payload = event.payload;
+  return (
+    typeof payload === "object" &&
+    payload !== null &&
+    (payload as { id?: unknown }).id === operationId
+  );
+}
+
+export type CodemodeSettlementWake = {
+  notify(): void;
+  /** Resolve on the next notification (or one already pending), a timeout or abort. */
+  wait(timeoutMs: number, signal?: AbortSignal): Promise<void>;
+};
+
+export function codemodeSettlementWake(): CodemodeSettlementWake {
+  let pending = false;
+  let release: (() => void) | null = null;
+  return {
+    notify() {
+      pending = true;
+      release?.();
+    },
+    async wait(timeoutMs, signal) {
+      if (!pending && !signal?.aborted) {
+        await new Promise<void>((resolve) => {
+          const done = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", done);
+            release = null;
+            resolve();
+          };
+          const timer = setTimeout(done, Math.max(0, timeoutMs));
+          signal?.addEventListener("abort", done, { once: true });
+          release = done;
+        });
+      }
+      pending = false;
+    },
+  };
+}
+
+/**
+ * Wait, within a budget, for an executing operation to settle. Waits only
+ * while the operation is queued or running; approval and terminal states
+ * return at once. Read failures keep the last known row.
+ */
+export async function awaitCodemodeSettlement(input: {
+  operation: CodemodeOperation;
+  read: () => Promise<CodemodeOperation | null>;
+  wake: CodemodeSettlementWake;
+  budgetMs: number;
+  fallbackReadMs: number;
+  signal?: AbortSignal;
+  now?: () => number;
+}): Promise<CodemodeOperation> {
+  const now = input.now ?? (() => performance.now());
+  const deadline = now() + input.budgetMs;
+  let operation = input.operation;
+  while (operation.state === "queued" || operation.state === "running") {
+    const remaining = deadline - now();
+    if (remaining <= 0 || input.signal?.aborted) break;
+    await input.wake.wait(Math.min(input.fallbackReadMs, remaining), input.signal);
+    if (input.signal?.aborted) break;
+    operation = (await input.read().catch(() => null)) ?? operation;
+  }
+  return operation;
+}
+
 export function codemodeOperationNeedsDispatch(operation: CodemodeOperation): boolean {
   return operation.state === "queued" || operation.state === "running";
 }
@@ -299,15 +492,19 @@ export async function readCodemodeOperation(
   deps: ApiRouteDeps,
   grant: AccessGrant,
   operationId: string,
+  options: { durableApproval?: boolean } = {},
 ): Promise<CodemodeOperation | null> {
-  if (!isCodemodeGrant(grant)) throw new CodemodeAuthorityError("invalid_grant");
-  const authority = codemodeAuthorityForGrant(grant)!;
-  return await getCodemodeOperation(deps.db, {
-    accountId: authority.accountId,
-    workspaceId: authority.workspaceId,
-    attemptId: authority.attemptId,
+  const { authority } = await requireActiveCodemodeCatalog(deps, grant);
+  const operation = await readTurnCodemodeOperation(deps.db, {
+    ...authority,
+    callerSubjectId: authority.subjectId,
     operationId,
   });
+  if (operation?.state === "waiting_for_approval" && !options.durableApproval)
+    throw new CodemodeToolApprovalRequiredError();
+  if (!operation || options.durableApproval) return operation;
+  const { durableApproval: _capability, approvalRequestId: _requestId, ...legacy } = operation;
+  return legacy;
 }
 
 function terminal(operation: CodemodeOperation): boolean {

package/src/codex-realtime.ts

@@ -13,12 +13,19 @@ import {
   type CodexRealtimeCallInput,
 } from "@opengeni/codex";
 import {
-  buildCodexTokenResolver,
+  acquireSubscriptionCoreCodexOperationLease,
+  buildSubscriptionCoreCodexConnectionTokenResolver,
+  buildSubscriptionCoreCodexOperationFetch,
+  listSubscriptionCoreCodexOperationCandidates,
+  readCodexCutoverDisposition,
+  readSubscriptionCoreSessionOwner,
+  releaseSubscriptionCoreCodexOperationLease,
+  renewSubscriptionCoreCodexOperationLease,
+  subscriptionCoreCodexPlanHasVoice,
+  type SubscriptionCoreCodexOperationLeaseRef,
+  type SubscriptionCoreCodexOperationScope,
   getActiveSessionHistoryItems,
-  getCodexCredentialStatus,
   getSessionRealtimeContinuityEntries,
-  getSessionCodexState,
-  listCodexAccountStatuses,
   type Database,
 } from "@opengeni/db";
 import { projectSessionRealtimeInitialItems } from "./session-realtime-context";
@@ -59,6 +66,13 @@ export type CodexRealtimeBrokerDependencies = {
     pinnedCredentialId: string | null;
     activeCredentialId: string | null;
     connectedCredentialIds: ReadonlySet<string>;
+    /**
+     * Connected credentials on a ChatGPT plan without voice (Free): the
+     * provider answers their realtime calls with 404.
+     */
+    voicelessCredentialIds?: ReadonlySet<string>;
+    /** Connected credentials open to new allocations whose plan has voice, in pool order. */
+    voiceCredentialIds?: readonly string[];
   }>;
   loadInitialItems(): Promise<CodexRealtimeInitialItem[]>;
   tokenResolver(credentialId: string): CodexTokenResolver;
@@ -104,12 +118,14 @@ The initial conversation items are authoritative context from the current sessio
 
 Live context wrapped in <session_user_message> is an authoritative user message already routed to the current session. A status of queued_for_execution means it is waiting behind existing work; accepted_for_execution means it is next with no existing work ahead; accepted_for_steering means it was given priority as a change of direction, while any prior work may still be yielding. Incorporate it immediately as conversation context, but never delegate it again or treat the wrapper metadata as user-authored text.
 
-Live context wrapped in <session_human_input_request> means current work is paused for the user's answer. Preserve the exact question meaning and options. Ask one question at a time when useful. The user may answer in the visible form or answer conversationally. If the user answers conversationally, create exactly one delegation containing the relevant question and the user's answer so the session agent can continue with complete context. If the user changes direction instead, delegate the new direction normally. Do not claim work resumed until session context confirms it.
+Live context wrapped in <session_human_input_request> means current work is paused for the user's answer. Preserve the exact question meaning and options. Ask one question at a time when useful. The user may answer in the visible form or answer conversationally. If the user answers conversationally, create exactly one delegation containing the relevant question and the user's answer so the session agent can continue with complete context. If the user changes direction instead, delegate the new direction normally. Do not claim work resumed until session context confirms it. A secret question (a password, key or code) is answered only in the app: say "answer it in the app", never ask for the secret aloud, and never delegate a spoken secret.
 
 Live context wrapped in <session_human_input_response> is the authoritative outcome of that pending question. An answered or skipped response came through the structured session UI and is already routed; incorporate it, never delegate it again, and acknowledge briefly only if useful. An expired or cancelled response means the question is no longer active.
 
 Live session updates may describe work that started before this realtime conversation, work sent directly by the user, or work delegated during an earlier realtime connection. Treat those updates as part of this same session even when they have no current delegation identity.
 
+For requests about another session, use the backend to find, select, inspect or act on it while staying in this conversation. Selecting a session alone does not authorize changing its work.
+
 ## Backend use
 
 For actions or tasks, always use the backend. If it is unclear whether backend use would help, use it.
@@ -189,11 +205,17 @@ export async function brokerSessionCodexRealtime(
     );
   }
   const selection = await deps.loadSelection();
-  const credentialId = selectCodexCredentialId({
+  const selected = selectCodexCredentialId({
     sessionPinnedCredentialId: selection.pinnedCredentialId,
     activeCredentialId: selection.activeCredentialId,
     connectedIds: selection.connectedCredentialIds,
   });
+  // A turn may run on a plan without voice; a call then takes another
+  // connected subscription that has it, when there is one.
+  const credentialId =
+    selected && selection.voicelessCredentialIds?.has(selected)
+      ? (selection.voiceCredentialIds?.[0] ?? selected)
+      : selected;
   if (!credentialId) {
     throw new CodexRealtimeBrokerError(
       "credential_unavailable",
@@ -253,59 +275,163 @@ export async function brokerSessionCodexRealtime(
   }
 }
 
-/** Bind the pure broker to OpenGeni's encrypted DB credential lifecycle. */
-export function buildSessionCodexRealtimeBroker(
+async function loadRealtimeInitialItems(
   db: Database,
-  settings: Settings,
   workspaceId: string,
   sessionId: string,
+): Promise<CodexRealtimeInitialItem[]> {
+  const [history, continuity] = await Promise.all([
+    getActiveSessionHistoryItems(db, workspaceId, sessionId),
+    getSessionRealtimeContinuityEntries(db, workspaceId, sessionId),
+  ]);
+  return projectSessionRealtimeInitialItems(history, continuity);
+}
+
+async function createRealtimeCall(
+  fetchImpl: CodexFetch,
+  auth: CodexAuthHeaders,
+  callInput: CodexRealtimeCallInput,
+  options: { signal?: AbortSignal | undefined },
+): Promise<CodexRealtimeProviderAnswer> {
+  const providerConfig = await fetchCodexRealtimeProviderConfig(auth, fetchImpl, options);
+  return await createCodexRealtimeCall(auth, callInput, fetchImpl, {
+    ...options,
+    providerConfig,
+  });
+}
+
+/**
+ * Codex realtime on the shared subscription core (M3 PR 2c, EP-N05..N07):
+ * each call resolves the session's recorded owner, places one shared
+ * organization- or workspace-scoped connection (the session's explicit
+ * choice first, then the effective primary, preferring a plan with voice),
+ * and holds its own `realtime` operation lease (session-bound, no turn)
+ * through negotiation, with refresh under the per-connection lock. The chat
+ * binding is never written; the client protocol and HTTP error translation
+ * are the legacy broker's.
+ */
+export async function brokerSessionCoreCodexRealtime(
+  db: Database,
+  settings: Settings,
+  context: { accountId: string; workspaceId: string; sessionId: string },
+  input: Omit<CodexRealtimeBrokerInput, "sessionId">,
   fetchImpl: CodexFetch = fetch,
-): (input: Omit<CodexRealtimeBrokerInput, "sessionId">) => Promise<CodexRealtimeProviderAnswer> {
-  return async (input) =>
-    await brokerSessionCodexRealtime(
-      {
-        enabled: settings.codexSubscriptionEnabled,
-        loadSelection: async () => {
-          const [sessionState, status, accounts] = await Promise.all([
-            getSessionCodexState(db, workspaceId, sessionId),
-            getCodexCredentialStatus(db, workspaceId),
-            listCodexAccountStatuses(db, workspaceId),
-          ]);
-          if (!sessionState) {
-            throw new CodexRealtimeBrokerError(
-              "credential_unavailable",
-              "Session is unavailable for Codex realtime",
-            );
-          }
-          return {
-            pinnedCredentialId: sessionState.pinnedCredentialId,
-            activeCredentialId: status?.credentialId ?? null,
-            connectedCredentialIds: new Set(
-              accounts
-                .filter((account) => account.status === "active")
-                .map((account) => account.id),
-            ),
-          };
-        },
-        loadInitialItems: async () => {
-          const [history, continuity] = await Promise.all([
-            getActiveSessionHistoryItems(db, workspaceId, sessionId),
-            getSessionRealtimeContinuityEntries(db, workspaceId, sessionId),
-          ]);
-          return projectSessionRealtimeInitialItems(history, continuity);
-        },
-        tokenResolver: (credentialId) =>
-          buildCodexTokenResolver(db, settings, workspaceId, credentialId),
-        createCall: async (auth, callInput, options) => {
-          const providerConfig = await fetchCodexRealtimeProviderConfig(auth, fetchImpl, options);
-          return await createCodexRealtimeCall(auth, callInput, fetchImpl, {
-            ...options,
-            providerConfig,
-          });
+): Promise<CodexRealtimeProviderAnswer> {
+  if (!settings.codexSubscriptionEnabled) {
+    throw new CodexRealtimeBrokerError(
+      "subscription_disabled",
+      "Connected Codex subscription realtime is disabled",
+    );
+  }
+  const owner = await readSubscriptionCoreSessionOwner(db, context);
+  if (!owner) {
+    throw new CodexRealtimeBrokerError(
+      "credential_unavailable",
+      "Session is unavailable for Codex realtime",
+    );
+  }
+  const scope: SubscriptionCoreCodexOperationScope = {
+    kind: "session",
+    ...context,
+    sessionOwnerSubjectId: owner.ownerSubjectId,
+  };
+  const candidates = await listSubscriptionCoreCodexOperationCandidates(db, scope);
+  // A turn may run on a plan without voice; a call takes a connection that
+  // has it whenever one exists (legacy parity).
+  const ordered = [
+    ...candidates.filter((candidate) => subscriptionCoreCodexPlanHasVoice(candidate.planType)),
+    ...candidates.filter((candidate) => !subscriptionCoreCodexPlanHasVoice(candidate.planType)),
+  ];
+  const operationId = crypto.randomUUID();
+  const attemptId = crypto.randomUUID();
+  for (const candidate of ordered) {
+    const ref: SubscriptionCoreCodexOperationLeaseRef = {
+      operationId,
+      attemptId,
+      operationKind: "realtime",
+      connectionId: candidate.connectionId,
+      holderId: `realtime:${context.sessionId}`,
+      generation: 1,
+    };
+    const lease = await acquireSubscriptionCoreCodexOperationLease(db, scope, ref);
+    if (lease.kind !== "acquired") continue;
+    try {
+      const resolver = buildSubscriptionCoreCodexConnectionTokenResolver(
+        db,
+        settings,
+        scope,
+        candidate.connectionId,
+        ref,
+      );
+      // Configuration and call creation are separate physical requests, as
+      // are both requests of the single authentication-only retry.
+      const requestFetch = buildSubscriptionCoreCodexOperationFetch(
+        db,
+        scope,
+        ref,
+        candidate.connectionId,
+        fetchImpl,
+      );
+      return await brokerSessionCodexRealtime(
+        {
+          enabled: true,
+          loadSelection: async () => ({
+            pinnedCredentialId: null,
+            activeCredentialId: candidate.connectionId,
+            connectedCredentialIds: new Set([candidate.connectionId]),
+          }),
+          loadInitialItems: () =>
+            loadRealtimeInitialItems(db, context.workspaceId, context.sessionId),
+          tokenResolver: () => resolver,
+          createCall: async (auth, callInput, options) => {
+            // Pre-dispatch fence on the exact operation lease.
+            if (!(await renewSubscriptionCoreCodexOperationLease(db, scope, ref))) {
+              throw new CodexRealtimeBrokerError(
+                "credential_unavailable",
+                "Codex subscription credential is unavailable",
+              );
+            }
+            return await createRealtimeCall(requestFetch, auth, callInput, options);
+          },
         },
-      },
-      { ...input, sessionId },
+        { ...input, sessionId: context.sessionId },
+      );
+    } finally {
+      await releaseSubscriptionCoreCodexOperationLease(db, scope, ref).catch(() => false);
+    }
+  }
+  throw new CodexRealtimeBrokerError(
+    "credential_unavailable",
+    "No connected Codex subscription is available for this session",
+  );
+}
+
+/** Bind the pure broker to Opengeni's encrypted DB credential lifecycle. */
+export function buildSessionCodexRealtimeBroker(
+  db: Database,
+  settings: Settings,
+  context: { accountId: string; workspaceId: string; sessionId: string },
+  fetchImpl: CodexFetch = fetch,
+): (input: Omit<CodexRealtimeBrokerInput, "sessionId">) => Promise<CodexRealtimeProviderAnswer> {
+  const { accountId, workspaceId, sessionId } = context;
+  return async (input) => {
+    // The account is required: without it a disabled cutover could not fail closed.
+    const disposition = await readCodexCutoverDisposition(db, accountId, workspaceId);
+    if (disposition === "maintenance") {
+      // A disabled cutover row is maintenance: fail closed, no legacy read.
+      throw new CodexRealtimeBrokerError(
+        "subscription_disabled",
+        "Connected Codex subscription realtime is disabled",
+      );
+    }
+    return await brokerSessionCoreCodexRealtime(
+      db,
+      settings,
+      { accountId, workspaceId, sessionId },
+      input,
+      fetchImpl,
     );
+  };
 }
 
 function credentialError(error: unknown): CodexRealtimeBrokerError {
@@ -322,6 +448,8 @@ function credentialError(error: unknown): CodexRealtimeBrokerError {
 }
 
 function brokerProviderError(error: unknown): CodexRealtimeBrokerError {
+  // A core pre-dispatch fence refusal is already typed (legacy calls never raise one).
+  if (error instanceof CodexRealtimeBrokerError) return error;
   if (!(error instanceof CodexRealtimeError)) {
     return new CodexRealtimeBrokerError("network_error", "Codex realtime provider request failed");
   }