@opengeni/sdk 0.52.1 → 1.0.1

package/src/codex-realtime-controller.ts

@@ -33,6 +33,7 @@ import type {
   GatewayRealtimeConnectResponse,
   EndSessionRealtimeRequest,
   RenewSessionRealtimeRequest,
+  SessionRealtimeInboundEntry,
   SessionRealtimeMode,
   SessionRealtimeModel,
   SessionRealtimeMutationResponse,
@@ -50,6 +51,27 @@ export const CODEX_REALTIME_NEGOTIATION_TIMEOUT_MS = 20_000;
 const DEFAULT_CONNECTION_ROTATION_INTERVAL_MS = 15 * 60_000;
 const DEFAULT_RECONNECT_BACKOFF_MS = [250, 1_000, 2_000, 5_000] as const;
 const OWNER_RECORD_VERSION = 1;
+const OWNER_DELEGATION_REPLAY_VERSION = 1;
+const OWNER_DELEGATION_REPLAY_MAX_CALLS = 4_096;
+const OWNER_DELEGATION_REPLAY_MAX_BYTES = 4 * 1024 * 1024;
+const SESSION_REALTIME_INBOUND_ENTRY_KEYS = new Set([
+  "operationId",
+  "kind",
+  "role",
+  "providerEventId",
+  "delegationItemId",
+  "text",
+  "payload",
+  "modelContext",
+]);
+const SESSION_REALTIME_INBOUND_KINDS = new Set([
+  "user_transcript",
+  "assistant_transcript",
+  "delegation_call",
+  "interruption",
+  "error",
+]);
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
 
 export type CodexRealtimeControllerStatus =
   | "idle"
@@ -123,6 +145,12 @@ export type CodexRealtimeControllerClient = {
     request: GatewayRealtimeConnectRequest,
     options?: { signal?: AbortSignal | undefined },
   ): Promise<GatewayRealtimeConnectResponse>;
+  negotiateXaiSubscriptionRealtime?(
+    workspaceId: string,
+    sessionId: string,
+    request: GatewayRealtimeConnectRequest,
+    options?: { signal?: AbortSignal | undefined },
+  ): Promise<GatewayRealtimeConnectResponse>;
   activateCodexRealtimeConnection(
     workspaceId: string,
     sessionId: string,
@@ -149,7 +177,9 @@ export type CodexRealtimeOwnerStorage = Pick<Storage, "getItem" | "setItem" | "r
 
 /** Canonical browser-owner storage namespace for a public realtime model. */
 export function sessionRealtimeOwnerStorageNamespace(model: SessionRealtimeModel): string {
-  return model === "gpt-live-1-boulder-alpha" ? "codex-realtime-owner" : "gateway-realtime-owner";
+  if (model === "gpt-live-1-boulder-alpha") return "codex-realtime-owner";
+  if (model === "supergrok/grok-voice-think-fast-2.0") return "xai-realtime-owner";
+  return "gateway-realtime-owner";
 }
 
 /** Canonical browser-owner storage key shared by the SDK controller and React facade. */
@@ -205,6 +235,8 @@ export type CreateCodexRealtimeControllerOptions = {
   model?: SessionRealtimeModel | undefined;
   ownerStorageNamespace?: string | undefined;
   startTransport?: RealtimeControllerTransportStarter | undefined;
+  /** Model-visible application context captured with each durable realtime message. */
+  getModelContext?: (() => string | undefined) | undefined;
 };
 
 export type RealtimeControllerTransportStarter = (input: {
@@ -250,6 +282,13 @@ type OwnerRecord = {
   operationId: string;
   browserInstanceId: string;
   ownerKey: string;
+  delegationReplay?: OwnerDelegationReplay | undefined;
+};
+
+type OwnerDelegationReplay = {
+  version: typeof OWNER_DELEGATION_REPLAY_VERSION;
+  acceptedDelegationItemIds: string[];
+  pendingDelegations: SessionRealtimeInboundEntry[];
 };
 
 type ConnectionRuntime = {
@@ -330,6 +369,59 @@ export function createCodexRealtimeController(
   let recoveryTerminal = false;
   let mutationTail = Promise.resolve();
   let connectionTask: Promise<void> | null = null;
+  const acceptedDelegationItemIds = new Set(
+    owner?.delegationReplay?.acceptedDelegationItemIds ?? [],
+  );
+  const pendingDelegations = new Map(
+    (owner?.delegationReplay?.pendingDelegations ?? []).flatMap((entry) =>
+      entry.delegationItemId ? [[entry.delegationItemId, entry] as const] : [],
+    ),
+  );
+
+  const invalidateStoredOwner = (): void => {
+    try {
+      storage?.removeItem(storageKey);
+    } catch {
+      // Best effort only. The bridge still fails closed and retains the exact
+      // in-memory snapshot for this controller's bounded recovery attempts.
+    }
+  };
+
+  const persistDelegationReplay = (input: {
+    acceptedDelegationItemIds: ReadonlySet<string>;
+    pendingDelegations: ReadonlyMap<string, SessionRealtimeInboundEntry>;
+  }): void => {
+    if (!owner || !storage) return;
+    const delegationReplay: OwnerDelegationReplay = {
+      version: OWNER_DELEGATION_REPLAY_VERSION,
+      acceptedDelegationItemIds: [...input.acceptedDelegationItemIds],
+      pendingDelegations: [...input.pendingDelegations.values()],
+    };
+    if (
+      delegationReplay.pendingDelegations.length > CODEX_REALTIME_V3_PENDING_MAX_ENTRIES ||
+      delegationReplay.acceptedDelegationItemIds.length +
+        delegationReplay.pendingDelegations.length >
+        OWNER_DELEGATION_REPLAY_MAX_CALLS
+    ) {
+      invalidateStoredOwner();
+      throw new Error("Realtime delegation replay journal exceeded its call limit");
+    }
+    const next: OwnerRecord = { ...owner, delegationReplay };
+    const serialized = JSON.stringify(next);
+    if (new TextEncoder().encode(serialized).byteLength > OWNER_DELEGATION_REPLAY_MAX_BYTES) {
+      invalidateStoredOwner();
+      throw new Error("Realtime delegation replay journal exceeded its byte limit");
+    }
+    try {
+      storage.setItem(storageKey, serialized);
+    } catch (error) {
+      // Never leave older ownership proof reloadable without the delegation
+      // snapshot that the active bridge just froze.
+      invalidateStoredOwner();
+      throw error;
+    }
+    owner = next;
+  };
 
   const publish = (patch: Partial<CodexRealtimeControllerSnapshot>): void => {
     state = { ...state, ...patch };
@@ -414,6 +506,8 @@ export function createCodexRealtimeController(
   const clearOwner = (): void => {
     owner = null;
     storage?.removeItem(storageKey);
+    acceptedDelegationItemIds.clear();
+    pendingDelegations.clear();
   };
 
   const transitionEnded = (message = "Realtime mode ended"): void => {
@@ -454,16 +548,26 @@ export function createCodexRealtimeController(
       publish({ microphone: "active" });
       return acquired;
     } catch (error) {
-      if (error instanceof CodexRealtimeMicrophoneError) {
-        const kind = error.code === "permission_denied" ? "permission_failure" : "device_failure";
+      const microphoneError =
+        error instanceof CodexRealtimeMicrophoneError
+          ? error
+          : signal.aborted && state.microphone === "acquiring"
+            ? new CodexRealtimeMicrophoneError(
+                "acquisition_failed",
+                "Microphone did not become available before voice startup timed out",
+              )
+            : null;
+      if (microphoneError) {
+        const kind =
+          microphoneError.code === "permission_denied" ? "permission_failure" : "device_failure";
         publish({
-          microphone: error.code,
+          microphone: microphoneError.code,
           status: state.mode?.state === "active" ? "recovering" : "error",
-          diagnostic: diagnostic(kind, error.message, true),
-          error: error.message,
+          diagnostic: diagnostic(kind, microphoneError.message, true),
+          error: microphoneError.message,
         });
       }
-      throw error;
+      throw microphoneError ?? error;
     }
   };
 
@@ -506,7 +610,10 @@ export function createCodexRealtimeController(
       });
       return;
     }
-    publish({ audibleOutput: next, ...(next === "audible" ? { error: null } : {}) });
+    publish({
+      audibleOutput: next,
+      ...(next === "audible" ? { error: null } : {}),
+    });
   };
 
   const startActiveIntervals = (): void => {
@@ -893,6 +1000,10 @@ export function createCodexRealtimeController(
         sync: async (request) =>
           await syncForGeneration(targetGeneration, activated.mode.id, request),
         randomUUID,
+        ...(options.getModelContext ? { getModelContext: options.getModelContext } : {}),
+        acceptedDelegationItemIds,
+        pendingDelegations,
+        onDelegationReplayStateChange: persistDelegationReplay,
         onSnapshot: (nextBridge) => {
           if (active?.generation === targetGeneration) publish({ bridge: nextBridge });
         },
@@ -1079,7 +1190,12 @@ export function createCodexRealtimeController(
           await handleConnectionFailure(error, "reconnect", false);
         } else {
           clearOwner();
-          publish({ status: "error", realtimeId: null, mode: null, error: safeError(error) });
+          publish({
+            status: "error",
+            realtimeId: null,
+            mode: null,
+            error: safeError(error),
+          });
         }
         throw error;
       }
@@ -1155,7 +1271,11 @@ export function createCodexRealtimeController(
       closed = false;
       stopping = false;
       owner = record;
-      publish({ status: "recovering", realtimeId: lifecycle.realtimeId, error: null });
+      publish({
+        status: "recovering",
+        realtimeId: lifecycle.realtimeId,
+        error: null,
+      });
       connectionTask = begin(record, true)
         .then(() => undefined)
         .catch(async (error) => {
@@ -1359,8 +1479,13 @@ function readOwnerRecord(
 ): OwnerRecord | null {
   const raw = storage?.getItem(key);
   if (!raw) return null;
+  if (new TextEncoder().encode(raw).byteLength > OWNER_DELEGATION_REPLAY_MAX_BYTES) {
+    storage?.removeItem(key);
+    return null;
+  }
   try {
     const parsed = recordValue(JSON.parse(raw));
+    const delegationReplay = readOwnerDelegationReplay(parsed?.delegationReplay);
     if (
       parsed?.version !== OWNER_RECORD_VERSION ||
       parsed.workspaceId !== scope.workspaceId ||
@@ -1368,18 +1493,120 @@ function readOwnerRecord(
       !stringValue(parsed.operationId) ||
       !stringValue(parsed.browserInstanceId) ||
       !stringValue(parsed.ownerKey) ||
-      String(parsed.ownerKey).length < 32
+      String(parsed.ownerKey).length < 32 ||
+      delegationReplay === null
     ) {
       storage?.removeItem(key);
       return null;
     }
-    return parsed as OwnerRecord;
+    return {
+      ...(parsed as Omit<OwnerRecord, "delegationReplay">),
+      ...(delegationReplay ? { delegationReplay } : {}),
+    };
   } catch {
     storage?.removeItem(key);
     return null;
   }
 }
 
+function readOwnerDelegationReplay(value: unknown): OwnerDelegationReplay | undefined | null {
+  if (value === undefined) return undefined;
+  const record = recordValue(value);
+  if (
+    record?.version !== OWNER_DELEGATION_REPLAY_VERSION ||
+    !Array.isArray(record.acceptedDelegationItemIds) ||
+    !Array.isArray(record.pendingDelegations) ||
+    record.acceptedDelegationItemIds.length + record.pendingDelegations.length >
+      OWNER_DELEGATION_REPLAY_MAX_CALLS ||
+    record.pendingDelegations.length > CODEX_REALTIME_V3_PENDING_MAX_ENTRIES
+  ) {
+    return null;
+  }
+  const acceptedDelegationItemIds: string[] = [];
+  const accepted = new Set<string>();
+  for (const candidate of record.acceptedDelegationItemIds) {
+    if (typeof candidate !== "string" || candidate.length < 1 || candidate.length > 1_024) {
+      return null;
+    }
+    if (!accepted.has(candidate)) {
+      accepted.add(candidate);
+      acceptedDelegationItemIds.push(candidate);
+    }
+  }
+  const pendingDelegations: SessionRealtimeInboundEntry[] = [];
+  const pendingIds = new Set<string>();
+  for (const candidate of record.pendingDelegations) {
+    const parsed = readSessionRealtimeInboundEntry(candidate);
+    if (
+      !parsed ||
+      parsed.kind !== "delegation_call" ||
+      !parsed.delegationItemId ||
+      accepted.has(parsed.delegationItemId) ||
+      pendingIds.has(parsed.delegationItemId)
+    ) {
+      return null;
+    }
+    pendingIds.add(parsed.delegationItemId);
+    pendingDelegations.push(parsed);
+  }
+  const replay: OwnerDelegationReplay = {
+    version: OWNER_DELEGATION_REPLAY_VERSION,
+    acceptedDelegationItemIds,
+    pendingDelegations,
+  };
+  if (
+    new TextEncoder().encode(JSON.stringify(replay)).byteLength > OWNER_DELEGATION_REPLAY_MAX_BYTES
+  ) {
+    return null;
+  }
+  return replay;
+}
+
+function readSessionRealtimeInboundEntry(value: unknown): SessionRealtimeInboundEntry | null {
+  const record = recordValue(value);
+  if (
+    !record ||
+    Object.keys(record).some((key) => !SESSION_REALTIME_INBOUND_ENTRY_KEYS.has(key)) ||
+    typeof record.operationId !== "string" ||
+    !UUID_PATTERN.test(record.operationId) ||
+    typeof record.kind !== "string" ||
+    !SESSION_REALTIME_INBOUND_KINDS.has(record.kind) ||
+    !optionalNullableEnum(record.role, ["user", "assistant"]) ||
+    !optionalNullableBoundedString(record.providerEventId, 1_024) ||
+    !optionalNullableBoundedString(record.delegationItemId, 1_024) ||
+    !optionalNullableBoundedString(record.text, 131_072) ||
+    (record.payload !== undefined && recordValue(record.payload) === null) ||
+    !optionalModelContext(record.modelContext)
+  ) {
+    return null;
+  }
+  return record as SessionRealtimeInboundEntry;
+}
+
+function optionalNullableEnum(value: unknown, allowed: readonly string[]): boolean {
+  return (
+    value === undefined || value === null || (typeof value === "string" && allowed.includes(value))
+  );
+}
+
+function optionalNullableBoundedString(value: unknown, maxLength: number): boolean {
+  return (
+    value === undefined ||
+    value === null ||
+    (typeof value === "string" && value.length <= maxLength)
+  );
+}
+
+function optionalModelContext(value: unknown): boolean {
+  return (
+    value === undefined ||
+    (typeof value === "string" &&
+      value.length >= 1 &&
+      value.length <= 32_768 &&
+      value.trim() === value)
+  );
+}
+
 function defaultStorage(): CodexRealtimeOwnerStorage | undefined {
   return typeof sessionStorage === "undefined" ? undefined : sessionStorage;
 }

package/src/codex-realtime-lifecycle.ts

@@ -66,6 +66,7 @@ export function projectSessionRealtimeLifecycle(
 
 function realtimeModel(value: unknown): SessionRealtimeModel | null {
   return value === "gpt-live-1-boulder-alpha" ||
+    value === "supergrok/grok-voice-think-fast-2.0" ||
     value === "opengeni-gateway/openai/gpt-realtime-2.1" ||
     value === "opengeni-gateway/openai/gpt-realtime-mini" ||
     value === "opengeni-gateway/xai/grok-voice-think-fast-2.0" ||

package/src/codex-realtime-v3.ts

@@ -35,9 +35,10 @@ export const CODEX_REALTIME_V3_PENDING_MAX_ENTRIES = 256;
 export const CODEX_REALTIME_V3_PENDING_MAX_BYTES = 16 * 1024 * 1024;
 const REALTIME_DELEGATION_TRANSCRIPT_MAX_BYTES = 65_536;
 const REALTIME_DELEGATION_INPUT_MAX_BYTES = 65_536;
+const REALTIME_MODEL_CONTEXT_MAX_CHARACTERS = 32_768;
 
 export type CodexRealtimeV3BridgeFatal = {
-  code: "pending_overflow";
+  code: "pending_overflow" | "replay_journal_failed";
   message: string;
 };
 
@@ -72,6 +73,19 @@ export type CodexRealtimeV3BridgeOptions = {
   >;
   sync(request: SyncSessionRealtimeLedgerRequest): Promise<SyncSessionRealtimeLedgerResponse>;
   randomUUID?: (() => string) | undefined;
+  /** Model-visible application context captured once for each durable message-bearing entry. */
+  getModelContext?: (() => string | undefined) | undefined;
+  /** Controller-lifetime delegation identities shared across provider connection rotations. */
+  acceptedDelegationItemIds?: Set<string> | undefined;
+  /** Unsynced delegation snapshots retained exactly across provider connection rotations. */
+  pendingDelegations?: Map<string, SessionRealtimeInboundEntry> | undefined;
+  /** Persist exact delegation replay state before it becomes browser-reload-sensitive. */
+  onDelegationReplayStateChange?:
+    | ((state: {
+        acceptedDelegationItemIds: ReadonlySet<string>;
+        pendingDelegations: ReadonlyMap<string, SessionRealtimeInboundEntry>;
+      }) => void)
+    | undefined;
   /** The controller installs its activation FIFO first, then enables this listener synchronously. */
   listen?: boolean | undefined;
   onSnapshot?: ((snapshot: CodexRealtimeV3BridgeSnapshot) => void) | undefined;
@@ -125,9 +139,32 @@ export function createCodexRealtimeV3Bridge(
   const clientReceivedSequences = new Set<number>();
   const sentSequences = new Set<number>();
   const finalizedTurnIds = new Set<string>();
+  const acceptedDelegationItemIds = options.acceptedDelegationItemIds ?? new Set<string>();
+  const pendingDelegations = options.pendingDelegations ?? new Map();
+  const locallyQueuedDelegationItemIds = new Set<string>();
   let transcriptSinceDelegation: FinalizedTranscript[] = [];
-  let pendingDelegationUserTranscript: { delegationItemId: string; text: string } | null = null;
+  let pendingDelegationUserTranscript: {
+    delegationItemId: string;
+    text: string;
+  } | null = null;
   const randomUUID = options.randomUUID ?? defaultRandomUUID;
+  const currentModelContext = (): string | undefined => {
+    let context: string | undefined;
+    try {
+      context = options.getModelContext?.()?.trim();
+    } catch {
+      lastError =
+        "Realtime model context callback failed; the provider message continued without application context";
+      return undefined;
+    }
+    if (!context) return undefined;
+    if (context.length > REALTIME_MODEL_CONTEXT_MAX_CHARACTERS) {
+      lastError =
+        "Realtime model context exceeded the 32768-character limit; the provider message continued without application context";
+      return undefined;
+    }
+    return context;
+  };
 
   const snapshot = (): CodexRealtimeV3BridgeSnapshot => ({
     connectionId: options.connectionId,
@@ -148,9 +185,9 @@ export function createCodexRealtimeV3Bridge(
   });
   const publish = (): void => options.onSnapshot?.(snapshot());
 
-  const triggerFatal = (message: string): void => {
+  const triggerFatalCode = (code: CodexRealtimeV3BridgeFatal["code"], message: string): void => {
     if (closed || fatal) return;
-    fatal = { code: "pending_overflow", message };
+    fatal = { code, message };
     lastError = message;
     publish();
     try {
@@ -161,6 +198,10 @@ export function createCodexRealtimeV3Bridge(
     }
   };
 
+  const triggerFatal = (message: string): void => {
+    triggerFatalCode("pending_overflow", message);
+  };
+
   const enqueue = (entry: SessionRealtimeInboundEntry): boolean => {
     if (closed || sealed || fatal) return false;
     const bytes = utf8ByteLength(JSON.stringify(entry));
@@ -177,6 +218,14 @@ export function createCodexRealtimeV3Bridge(
     return true;
   };
 
+  // Same-browser reload reconstructs this exact map from the persisted owner
+  // journal. Queue those first-frozen calls before listening to the replacement
+  // provider connection; startup proof or a duplicate call drives the normal
+  // flush path without resampling application context.
+  for (const [delegationItemId, entry] of pendingDelegations) {
+    if (enqueue(entry)) locallyQueuedDelegationItemIds.add(delegationItemId);
+  }
+
   const hasWork = (): boolean =>
     pendingInbound.length > 0 ||
     (!providerStartedAccepted && providerStarted !== undefined) ||
@@ -213,7 +262,46 @@ export function createCodexRealtimeV3Bridge(
         throw error;
       }
 
+      const acceptedAfterSync = new Set(acceptedDelegationItemIds);
+      const pendingAfterSync = new Map(pendingDelegations);
+      let delegationReplayChanged = false;
+      for (const item of batch) {
+        if (item.entry.kind === "delegation_call" && item.entry.delegationItemId) {
+          delegationReplayChanged = true;
+          acceptedAfterSync.add(item.entry.delegationItemId);
+          if (pendingAfterSync.get(item.entry.delegationItemId) === item.entry) {
+            pendingAfterSync.delete(item.entry.delegationItemId);
+          }
+        }
+      }
+      if (delegationReplayChanged) {
+        try {
+          options.onDelegationReplayStateChange?.({
+            acceptedDelegationItemIds: acceptedAfterSync,
+            pendingDelegations: pendingAfterSync,
+          });
+        } catch (error) {
+          // The server may already have admitted this exact batch. Keep it
+          // queued with the original operation identity and stop this bridge.
+          // Recovery can safely replay it because the prior pending journal
+          // state remains authoritative until the accepted transition writes.
+          pendingInbound = [...batch, ...pendingInbound];
+          triggerFatalCode(
+            "replay_journal_failed",
+            `Codex realtime delegation replay journal failed: ${safeError(error)}`,
+          );
+          return;
+        }
+      }
+
       for (const item of batch) {
+        if (item.entry.kind === "delegation_call" && item.entry.delegationItemId) {
+          acceptedDelegationItemIds.add(item.entry.delegationItemId);
+          if (pendingDelegations.get(item.entry.delegationItemId) === item.entry) {
+            pendingDelegations.delete(item.entry.delegationItemId);
+          }
+          locallyQueuedDelegationItemIds.delete(item.entry.delegationItemId);
+        }
         pendingInboundCount -= 1;
         pendingInboundBytes -= item.bytes;
       }
@@ -345,31 +433,67 @@ export function createCodexRealtimeV3Bridge(
       // These events are provider UI deltas. `turn.done` is the single
       // authoritative finalized transcript persisted below.
     } else if (event.type === "delegation.created") {
-      activeDelegationId = event.delegationItemId;
-      const transcript = delegationTranscript(transcriptSinceDelegation, event.inputTranscript);
-      const coveredTurnIds = transcriptSinceDelegation.map((entry) => entry.turnId);
-      durable = enqueue({
-        operationId: randomUUID(),
-        kind: "delegation_call",
-        providerEventId: event.providerEventId,
-        delegationItemId: event.delegationItemId,
-        text: renderRealtimeDelegationInput(event.inputTranscript, transcript),
-        payload: {
-          offsetMs: event.offsetMs,
-          inputTranscript: event.inputTranscript,
-          transcriptFenceTurnIds: coveredTurnIds,
-        },
-      });
-      if (durable) {
-        const alreadyFinalized = transcriptSinceDelegation.some(
-          (entry) =>
-            entry.role === "user" &&
-            normalizedTranscript(entry.text) === normalizedTranscript(event.inputTranscript),
-        );
-        pendingDelegationUserTranscript = alreadyFinalized
-          ? null
-          : { delegationItemId: event.delegationItemId, text: event.inputTranscript };
-        transcriptSinceDelegation = [];
+      if (acceptedDelegationItemIds.has(event.delegationItemId)) {
+        ignoredEventCount += 1;
+        lastIgnoredEventType = event.type;
+      } else if (locallyQueuedDelegationItemIds.has(event.delegationItemId)) {
+        ignoredEventCount += 1;
+        lastIgnoredEventType = event.type;
+        durable = true;
+      } else {
+        let entry = pendingDelegations.get(event.delegationItemId);
+        if (!entry) {
+          const transcript = delegationTranscript(transcriptSinceDelegation, event.inputTranscript);
+          const coveredTurnIds = transcriptSinceDelegation.map((item) => item.turnId);
+          const modelContext = currentModelContext();
+          entry = {
+            operationId: randomUUID(),
+            kind: "delegation_call",
+            providerEventId: event.providerEventId,
+            delegationItemId: event.delegationItemId,
+            text: renderRealtimeDelegationInput(event.inputTranscript, transcript),
+            payload: {
+              offsetMs: event.offsetMs,
+              inputTranscript: event.inputTranscript,
+              transcriptFenceTurnIds: coveredTurnIds,
+            },
+            ...(modelContext ? { modelContext } : {}),
+          };
+          pendingDelegations.set(event.delegationItemId, entry);
+        }
+        try {
+          options.onDelegationReplayStateChange?.({
+            acceptedDelegationItemIds,
+            pendingDelegations,
+          });
+        } catch (error) {
+          triggerFatalCode(
+            "replay_journal_failed",
+            `Codex realtime delegation replay journal failed: ${safeError(error)}`,
+          );
+          return Promise.resolve();
+        }
+        durable = enqueue(entry);
+        if (durable) {
+          locallyQueuedDelegationItemIds.add(event.delegationItemId);
+          activeDelegationId = event.delegationItemId;
+          const frozenInputTranscript =
+            typeof entry.payload.inputTranscript === "string"
+              ? entry.payload.inputTranscript
+              : event.inputTranscript;
+          const alreadyFinalized = transcriptSinceDelegation.some(
+            (item) =>
+              item.role === "user" &&
+              normalizedTranscript(item.text) === normalizedTranscript(frozenInputTranscript),
+          );
+          pendingDelegationUserTranscript = alreadyFinalized
+            ? null
+            : {
+                delegationItemId: event.delegationItemId,
+                text: frozenInputTranscript,
+              };
+          transcriptSinceDelegation = [];
+        }
       }
     } else if (event.type === "output_audio.delta") {
       speaking = true;
@@ -383,7 +507,9 @@ export function createCodexRealtimeV3Bridge(
             normalizedTranscript(pendingDelegationUserTranscript.text)
             ? pendingDelegationUserTranscript.delegationItemId
             : null;
-        durable = enqueue(finalTranscript(randomUUID, event, coveredByDelegationItemId));
+        durable = enqueue(
+          finalTranscript(randomUUID, event, coveredByDelegationItemId, currentModelContext()),
+        );
         if (durable) {
           finalizedTurnIds.add(event.turnId);
           if (coveredByDelegationItemId) {
@@ -446,6 +572,7 @@ function finalTranscript(
   randomUUID: () => string,
   event: Extract<CodexRealtimeV3Event, { type: "turn.done" }>,
   coveredByDelegationItemId: string | null,
+  modelContext: string | undefined,
 ): SessionRealtimeInboundEntry {
   return {
     operationId: randomUUID(),
@@ -456,6 +583,7 @@ function finalTranscript(
       turnId: event.turnId,
       ...(coveredByDelegationItemId ? { coveredByDelegationItemId } : {}),
     },
+    ...(modelContext ? { modelContext } : {}),
   };
 }
 
@@ -539,7 +667,10 @@ function sendOutbound(events: RTCDataChannel, entry: SessionRealtimeLedgerEntry)
           text,
           channel: payloadChannel ?? "speakable",
         })
-      : encodeCodexRealtimeV3SessionContextAppend({ text, channel: payloadChannel });
+      : encodeCodexRealtimeV3SessionContextAppend({
+          text,
+          channel: payloadChannel,
+        });
   for (const message of messages) events.send(JSON.stringify(message));
 }
 

package/src/desktop.ts

@@ -71,13 +71,23 @@ export interface DesktopRfbLike {
     type: "connect" | "disconnect" | "securityfailure",
     cb: (e?: unknown) => void,
   ) => void;
+  /** Send clipboard text over the already-open RFB connection. */
+  clipboardPasteFrom?(text: string): void;
+  /** Send one RFB key event. A missing `down` emits a complete key press. */
+  sendKey?(keysym: number, code: string, down?: boolean): void;
+  /** Focus or release the RFB keyboard sink without reconnecting. */
+  focus?(options?: FocusOptions): void;
+  blur?(): void;
   disconnect(): void;
 }
 
 export type DesktopRfbFactory = (
   target: HTMLElement,
   url: string,
-  opts: { credentials?: { password?: string | undefined } | undefined },
+  opts: {
+    credentials?: { password?: string | undefined } | undefined;
+    wsProtocols?: string[] | undefined;
+  },
 ) => DesktopRfbLike;
 
 export type DesktopConnectionState =