@opengeni/codex 0.2.9 → 0.2.10

package/dist/realtime-v3.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Codex GPT-Live Frameless Bidi (V3) wire adapter.
+ *
+ * These shapes are pinned to openai/codex@fa1d4c40. V3 delegates work with
+ * `delegation.created`; it does not expose the ordinary Realtime V2
+ * `function_call` protocol.
+ */
+export declare const CODEX_REALTIME_INITIAL_ITEMS_MAX_COUNT = 128;
+export declare const CODEX_REALTIME_INITIAL_ITEMS_MAX_TOKENS = 8192;
+export declare const CODEX_REALTIME_CONTEXT_APPEND_MAX_BYTES = 500;
+export declare const CODEX_REALTIME_V3_MAX_EVENT_BYTES = 1048576;
+export declare const CODEX_REALTIME_V3_MAX_IDENTIFIER_BYTES = 1024;
+export declare const CODEX_REALTIME_V3_MAX_TEXT_BYTES = 131072;
+export type CodexRealtimeInitialItem = {
+    role: "user" | "developer" | "assistant";
+    text: string;
+};
+type ProviderEventIdentity = {
+    providerEventId: string | null;
+};
+export type CodexRealtimeV3Event = (ProviderEventIdentity & {
+    type: "session.started" | "session.updated";
+    sessionId: string;
+    instructions: string | null;
+}) | (ProviderEventIdentity & {
+    type: "input_transcript.added" | "output_transcript.added";
+    itemId: string | null;
+    text: string;
+}) | (ProviderEventIdentity & {
+    type: "output_audio.delta";
+    audio: string;
+    startMs: number | null;
+    endMs: number | null;
+}) | (ProviderEventIdentity & {
+    type: "turn.done";
+    turnId: string;
+    role: "user" | "assistant";
+    transcript: string;
+}) | (ProviderEventIdentity & {
+    type: "delegation.created";
+    delegationItemId: string;
+    inputTranscript: string;
+    offsetMs: number | null;
+}) | (ProviderEventIdentity & {
+    type: "error";
+    message: string;
+});
+export type CodexRealtimeV3ParseFailure = {
+    ok: false;
+    reason: "invalid_json" | "missing_type" | "unsupported_type" | "invalid_shape" | "oversized_event" | "oversized_field";
+    eventType: string | null;
+};
+export type CodexRealtimeV3ParseResult = {
+    ok: true;
+    event: CodexRealtimeV3Event;
+} | CodexRealtimeV3ParseFailure;
+export type CodexRealtimeV3ContextAppendChannel = "speakable" | "commentary";
+export type CodexRealtimeV3DelegationContextAppend = {
+    type: "delegation.context.append";
+    delegation_item_id: string;
+    channel?: CodexRealtimeV3ContextAppendChannel | undefined;
+    content: Array<{
+        type: "input_text";
+        text: string;
+    }>;
+};
+export type CodexRealtimeV3SessionContextAppend = {
+    type: "session.context.append";
+    channel?: CodexRealtimeV3ContextAppendChannel | undefined;
+    content: Array<{
+        type: "input_text";
+        text: string;
+    }>;
+};
+export declare function parseCodexRealtimeV3Event(payload: string): CodexRealtimeV3ParseResult;
+export declare function encodeCodexRealtimeV3DelegationContextAppend(input: {
+    delegationItemId: string;
+    text: string;
+    channel?: CodexRealtimeV3ContextAppendChannel | undefined;
+}): CodexRealtimeV3DelegationContextAppend[];
+export declare function encodeCodexRealtimeV3SessionContextAppend(input: {
+    text: string;
+    channel?: CodexRealtimeV3ContextAppendChannel | undefined;
+}): CodexRealtimeV3SessionContextAppend[];
+export declare function contextAppendChunks(text: string): string[];
+export {};

package/dist/realtime-v3.js

@@ -0,0 +1,25 @@
+import {
+  CODEX_REALTIME_CONTEXT_APPEND_MAX_BYTES,
+  CODEX_REALTIME_INITIAL_ITEMS_MAX_COUNT,
+  CODEX_REALTIME_INITIAL_ITEMS_MAX_TOKENS,
+  CODEX_REALTIME_V3_MAX_EVENT_BYTES,
+  CODEX_REALTIME_V3_MAX_IDENTIFIER_BYTES,
+  CODEX_REALTIME_V3_MAX_TEXT_BYTES,
+  contextAppendChunks,
+  encodeCodexRealtimeV3DelegationContextAppend,
+  encodeCodexRealtimeV3SessionContextAppend,
+  parseCodexRealtimeV3Event
+} from "./chunk-MFVGCR3N.js";
+export {
+  CODEX_REALTIME_CONTEXT_APPEND_MAX_BYTES,
+  CODEX_REALTIME_INITIAL_ITEMS_MAX_COUNT,
+  CODEX_REALTIME_INITIAL_ITEMS_MAX_TOKENS,
+  CODEX_REALTIME_V3_MAX_EVENT_BYTES,
+  CODEX_REALTIME_V3_MAX_IDENTIFIER_BYTES,
+  CODEX_REALTIME_V3_MAX_TEXT_BYTES,
+  contextAppendChunks,
+  encodeCodexRealtimeV3DelegationContextAppend,
+  encodeCodexRealtimeV3SessionContextAppend,
+  parseCodexRealtimeV3Event
+};
+//# sourceMappingURL=realtime-v3.js.map

package/dist/realtime-v3.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/realtime.d.ts

@@ -0,0 +1,48 @@
+import { type CodexAuthHeaders } from "./api-client";
+import { CODEX_REALTIME_MODEL, CODEX_REALTIME_VERSION } from "./constants";
+import type { CodexFetch } from "./device-code";
+import { type CodexRealtimeInitialItem } from "./realtime-v3";
+export declare const CODEX_REALTIME_VOICES: readonly ["juniper", "maple", "spruce", "ember", "vale", "breeze", "arbor", "sol", "cove"];
+export type CodexRealtimeVoice = (typeof CODEX_REALTIME_VOICES)[number];
+export type CodexRealtimeCallInput = {
+    /** Browser-created WebRTC offer. It must negotiate an audio media section. */
+    sdp: string;
+    /** This transport intentionally supports only Codex's Frameless/V3 protocol. */
+    version: typeof CODEX_REALTIME_VERSION;
+    /** Server-owned session/thread binding; sent upstream but never returned. */
+    sessionId: string;
+    /** Server-projected ordinary-session history for Frameless V3 bootstrap. */
+    initialItems?: CodexRealtimeInitialItem[] | undefined;
+    instructions?: string | undefined;
+    voice?: CodexRealtimeVoice | undefined;
+};
+export type CodexRealtimeCallResult = {
+    sdp: string;
+    version: typeof CODEX_REALTIME_VERSION;
+    model: typeof CODEX_REALTIME_MODEL;
+};
+export type CodexRealtimeErrorCode = "invalid_request" | "incompatible" | "authentication" | "entitlement" | "rate_limited" | "provider" | "invalid_response" | "network" | "timeout" | "cancelled";
+/** Safe provider failure: it contains no response body, credential, or account identity. */
+export declare class CodexRealtimeError extends Error {
+    readonly code: CodexRealtimeErrorCode;
+    readonly providerStatus: number | null;
+    constructor(code: CodexRealtimeErrorCode, message: string, providerStatus?: number | null);
+}
+export type CodexRealtimeCallOptions = {
+    signal?: AbortSignal | undefined;
+    timeoutMs?: number | undefined;
+};
+/**
+ * Create one native subscription-authenticated Codex GPT-Live V3 WebRTC call.
+ *
+ * There is deliberately no API-key or WebSocket fallback and no transport
+ * retry. A caller may refresh the same connected subscription after one 401,
+ * but this adapter always performs exactly one provider request.
+ */
+export declare function createCodexRealtimeCall(auth: CodexAuthHeaders, input: CodexRealtimeCallInput, fetchImpl?: CodexFetch, options?: CodexRealtimeCallOptions): Promise<CodexRealtimeCallResult>;
+/** Shared pin→active selection for worker turns and direct realtime calls. */
+export declare function selectCodexCredentialId(args: {
+    sessionPinnedCredentialId: string | null;
+    activeCredentialId: string | null;
+    connectedIds: ReadonlySet<string>;
+}): string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/codex",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "description": "ChatGPT/Codex subscription auth + transport: device-code login, token refresh, and the Responses-backend fetch. Pure HTTP + transforms; no database dependency.",
   "license": "Apache-2.0",
   "repository": {
@@ -25,6 +25,10 @@
     "./constants": {
       "types": "./dist/constants.d.ts",
       "import": "./dist/constants.js"
+    },
+    "./realtime-v3": {
+      "types": "./dist/realtime-v3.d.ts",
+      "import": "./dist/realtime-v3.js"
     }
   },
   "publishConfig": {

package/src/api-client.ts

@@ -28,7 +28,8 @@ export type ResetCreditFetchFailureReason =
   | "network_error"
   | "timeout";
 
-function subscriptionHeaders(a: CodexAuthHeaders): Record<string, string> {
+/** Server-only headers shared by every ChatGPT/Codex subscription transport. */
+export function codexSubscriptionHeaders(a: CodexAuthHeaders): Record<string, string> {
   return {
     Authorization: `Bearer ${a.accessToken}`,
     ...(a.chatgptAccountId ? { "ChatGPT-Account-ID": a.chatgptAccountId } : {}),
@@ -48,7 +49,7 @@ export async function fetchCodexModels(
   const fetched = await runBoundedCodexOperation(async (signal) => {
     const res = await fetchImpl(
       `${CODEX_RESPONSES_BASE}/models?client_version=${encodeURIComponent(a.clientVersion)}`,
-      { method: "GET", headers: subscriptionHeaders(a), signal },
+      { method: "GET", headers: codexSubscriptionHeaders(a), signal },
     );
     if (!res.ok) {
       await res.arrayBuffer().catch(() => undefined);
@@ -72,7 +73,7 @@ export async function fetchCodexUsage(
   const fetched = await runBoundedCodexOperation(async (signal) => {
     const res = await fetchImpl(`${CODEX_WHAM_BASE}/wham/usage`, {
       method: "GET",
-      headers: subscriptionHeaders(a),
+      headers: codexSubscriptionHeaders(a),
       signal,
     });
     // A 404 may carry a usage-limit body; the route layer normalizes it to a limits state (spec §1.8c).
@@ -102,19 +103,27 @@ export async function fetchCodexRateLimitResetCredits(
   const fetched = await runBoundedCodexOperation(async (signal) => {
     const res = await fetchImpl(`${CODEX_WHAM_BASE}/wham/rate-limit-reset-credits`, {
       method: "GET",
-      headers: subscriptionHeaders(a),
+      headers: codexSubscriptionHeaders(a),
       signal,
     });
     if (!res.ok) {
       // Drain the body without retaining/logging it. Provider error bodies may
       // contain account-specific details and are not part of this contract.
       await res.arrayBuffer().catch(() => undefined);
-      return { ok: false as const, status: res.status, reason: "http_error" as const };
+      return {
+        ok: false as const,
+        status: res.status,
+        reason: "http_error" as const,
+      };
     }
     const details = parseCodexRateLimitResetCreditsDetails(await res.json().catch(() => null));
     return details
       ? { ok: true as const, status: res.status, details }
-      : { ok: false as const, status: res.status, reason: "invalid_response" as const };
+      : {
+          ok: false as const,
+          status: res.status,
+          reason: "invalid_response" as const,
+        };
   }, timeoutMs);
   return fetched.ok ? fetched.value : { ok: false, status: 0, reason: fetched.reason };
 }
@@ -146,7 +155,7 @@ export async function consumeCodexRateLimitResetCredit(
     const res = await fetchImpl(`${CODEX_WHAM_BASE}/wham/rate-limit-reset-credits/consume`, {
       method: "POST",
       headers: {
-        ...subscriptionHeaders(a),
+        ...codexSubscriptionHeaders(a),
         "content-type": "application/json",
       },
       body: JSON.stringify({
@@ -157,12 +166,20 @@ export async function consumeCodexRateLimitResetCredit(
     });
     if (!res.ok) {
       await res.arrayBuffer().catch(() => undefined);
-      return { ok: false as const, status: res.status, reason: "http_error" as const };
+      return {
+        ok: false as const,
+        status: res.status,
+        reason: "http_error" as const,
+      };
     }
     const result = parseCodexRateLimitResetConsumeResponse(await res.json().catch(() => null));
     return result
       ? { ok: true as const, status: res.status, result }
-      : { ok: false as const, status: res.status, reason: "invalid_response" as const };
+      : {
+          ok: false as const,
+          status: res.status,
+          reason: "invalid_response" as const,
+        };
   }, timeoutMs);
   return fetched.ok ? fetched.value : { ok: false, status: 0, reason: fetched.reason };
 }

package/src/constants.ts

@@ -52,7 +52,14 @@ export const CODEX_MODEL_AUTO_COMPACT_TOKEN_LIMIT = Math.floor(
 // 2026-07-09: 0.142.4 filtered every GPT-5.6 slug out of GET /models, while the
 // official Codex 0.144.0+ releases return all three exact slugs above. Keep
 // this pinned to the latest stable Codex release we have verified end-to-end.
-export const CODEX_CLIENT_VERSION = "0.144.6";
+export const CODEX_CLIENT_VERSION = "0.145.0";
+
+// Native ChatGPT/Codex subscription WebRTC call creation. Verified against
+// openai/codex 0.145.0 commit bd2de422aa287b97b06ca6425a10935bcf1b3731.
+export const CODEX_REALTIME_MODEL = "gpt-live-1-boulder-alpha";
+export const CODEX_REALTIME_VERSION = "v3";
+export const CODEX_REALTIME_DEFAULT_VOICE = "cove";
+export const CODEX_REALTIME_CALL_TIMEOUT_MS = 15_000;
 
 export const CODEX_REFRESH_WINDOW_MS = 5 * 60 * 1000; // proactive refresh when within 5 min of exp (spec §1.1)
 export const CODEX_REFRESH_FALLBACK_MS = 8 * 24 * 60 * 60 * 1000; // 8 days when exp is unparseable

package/src/index.ts

@@ -11,3 +11,5 @@ export * from "./response-timeout";
 export * from "./fetch";
 export * from "./mcp-sanitize";
 export * from "./model-output-truncation";
+export * from "./realtime";
+export * from "./realtime-v3";

package/src/realtime-v3.ts

@@ -0,0 +1,349 @@
+/**
+ * Codex GPT-Live Frameless Bidi (V3) wire adapter.
+ *
+ * These shapes are pinned to openai/codex@fa1d4c40. V3 delegates work with
+ * `delegation.created`; it does not expose the ordinary Realtime V2
+ * `function_call` protocol.
+ */
+
+export const CODEX_REALTIME_INITIAL_ITEMS_MAX_COUNT = 128;
+export const CODEX_REALTIME_INITIAL_ITEMS_MAX_TOKENS = 8_192;
+export const CODEX_REALTIME_CONTEXT_APPEND_MAX_BYTES = 500;
+export const CODEX_REALTIME_V3_MAX_EVENT_BYTES = 1_048_576;
+export const CODEX_REALTIME_V3_MAX_IDENTIFIER_BYTES = 1_024;
+export const CODEX_REALTIME_V3_MAX_TEXT_BYTES = 131_072;
+
+export type CodexRealtimeInitialItem = {
+  role: "user" | "developer" | "assistant";
+  text: string;
+};
+
+type ProviderEventIdentity = {
+  providerEventId: string | null;
+};
+
+export type CodexRealtimeV3Event =
+  | (ProviderEventIdentity & {
+      type: "session.started" | "session.updated";
+      sessionId: string;
+      instructions: string | null;
+    })
+  | (ProviderEventIdentity & {
+      type: "input_transcript.added" | "output_transcript.added";
+      itemId: string | null;
+      text: string;
+    })
+  | (ProviderEventIdentity & {
+      type: "output_audio.delta";
+      audio: string;
+      startMs: number | null;
+      endMs: number | null;
+    })
+  | (ProviderEventIdentity & {
+      type: "turn.done";
+      turnId: string;
+      role: "user" | "assistant";
+      transcript: string;
+    })
+  | (ProviderEventIdentity & {
+      type: "delegation.created";
+      delegationItemId: string;
+      inputTranscript: string;
+      offsetMs: number | null;
+    })
+  | (ProviderEventIdentity & {
+      type: "error";
+      message: string;
+    });
+
+export type CodexRealtimeV3ParseFailure = {
+  ok: false;
+  reason:
+    | "invalid_json"
+    | "missing_type"
+    | "unsupported_type"
+    | "invalid_shape"
+    | "oversized_event"
+    | "oversized_field";
+  eventType: string | null;
+};
+
+export type CodexRealtimeV3ParseResult =
+  | { ok: true; event: CodexRealtimeV3Event }
+  | CodexRealtimeV3ParseFailure;
+
+export type CodexRealtimeV3ContextAppendChannel = "speakable" | "commentary";
+
+export type CodexRealtimeV3DelegationContextAppend = {
+  type: "delegation.context.append";
+  delegation_item_id: string;
+  channel?: CodexRealtimeV3ContextAppendChannel | undefined;
+  content: Array<{ type: "input_text"; text: string }>;
+};
+
+export type CodexRealtimeV3SessionContextAppend = {
+  type: "session.context.append";
+  channel?: CodexRealtimeV3ContextAppendChannel | undefined;
+  content: Array<{ type: "input_text"; text: string }>;
+};
+
+export function parseCodexRealtimeV3Event(payload: string): CodexRealtimeV3ParseResult {
+  if (utf8ByteLength(payload) > CODEX_REALTIME_V3_MAX_EVENT_BYTES) {
+    return failure("oversized_event", null);
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(payload);
+  } catch {
+    return failure("invalid_json", null);
+  }
+  const event = record(value);
+  const typeField = boundedStringField(event, "type", CODEX_REALTIME_V3_MAX_IDENTIFIER_BYTES);
+  if (typeField.oversized) return failure("oversized_field", null);
+  const type = typeField.value;
+  if (!type) return failure("missing_type", null);
+  const providerEventIdField = firstBoundedStringField(
+    event,
+    ["event_id", "id"],
+    CODEX_REALTIME_V3_MAX_IDENTIFIER_BYTES,
+  );
+  if (providerEventIdField.oversized) return failure("oversized_field", type);
+  const providerEventId = providerEventIdField.value ?? null;
+
+  if (type === "session.started" || type === "session.updated") {
+    const session = record(event.session);
+    const sessionIdField = boundedStringField(
+      session,
+      "id",
+      CODEX_REALTIME_V3_MAX_IDENTIFIER_BYTES,
+    );
+    const instructionsField = boundedStringField(
+      session,
+      "instructions",
+      CODEX_REALTIME_V3_MAX_TEXT_BYTES,
+    );
+    if (sessionIdField.oversized || instructionsField.oversized) {
+      return failure("oversized_field", type);
+    }
+    const sessionId = sessionIdField.value;
+    if (!sessionId) return failure("invalid_shape", type);
+    return {
+      ok: true,
+      event: {
+        type,
+        providerEventId,
+        sessionId,
+        instructions: instructionsField.value ?? null,
+      },
+    };
+  }
+
+  if (type === "input_transcript.added" || type === "output_transcript.added") {
+    const item = record(event.item);
+    const itemIdField = boundedStringField(item, "id", CODEX_REALTIME_V3_MAX_IDENTIFIER_BYTES);
+    const textField = boundedStringField(item, "text", CODEX_REALTIME_V3_MAX_TEXT_BYTES);
+    if (itemIdField.oversized || textField.oversized) {
+      return failure("oversized_field", type);
+    }
+    const text = textField.value;
+    if (text === undefined) return failure("invalid_shape", type);
+    return {
+      ok: true,
+      event: {
+        type,
+        providerEventId,
+        itemId: itemIdField.value ?? null,
+        text,
+      },
+    };
+  }
+
+  if (type === "output_audio.delta") {
+    const audio = stringField(event, "audio");
+    if (audio === undefined) return failure("invalid_shape", type);
+    return {
+      ok: true,
+      event: {
+        type,
+        providerEventId,
+        audio,
+        startMs: finiteNumberField(event, "start_ms"),
+        endMs: finiteNumberField(event, "end_ms"),
+      },
+    };
+  }
+
+  if (type === "turn.done") {
+    const turn = record(event.turn);
+    const turnIdField = boundedStringField(turn, "id", CODEX_REALTIME_V3_MAX_IDENTIFIER_BYTES);
+    const transcriptField = boundedStringField(
+      turn,
+      "transcript",
+      CODEX_REALTIME_V3_MAX_TEXT_BYTES,
+    );
+    if (turnIdField.oversized || transcriptField.oversized) {
+      return failure("oversized_field", type);
+    }
+    const turnId = turnIdField.value;
+    const role = stringField(turn, "role");
+    const transcript = transcriptField.value;
+    if (!turnId || (role !== "user" && role !== "assistant") || transcript === undefined) {
+      return failure("invalid_shape", type);
+    }
+    return {
+      ok: true,
+      event: { type, providerEventId, turnId, role, transcript },
+    };
+  }
+
+  if (type === "delegation.created") {
+    const item = record(event.item);
+    const delegationItemIdField = boundedStringField(
+      item,
+      "id",
+      CODEX_REALTIME_V3_MAX_IDENTIFIER_BYTES,
+    );
+    if (delegationItemIdField.oversized) return failure("oversized_field", type);
+    const delegationItemId = delegationItemIdField.value;
+    if (
+      !delegationItemId ||
+      stringField(item, "type") !== "delegation" ||
+      stringField(item, "target") !== "client" ||
+      !Array.isArray(item.content)
+    ) {
+      return failure("invalid_shape", type);
+    }
+    const inputParts: string[] = [];
+    let inputBytes = 0;
+    for (const rawContent of item.content) {
+      const content = record(rawContent);
+      if (stringField(content, "type") !== "input_text") continue;
+      const textField = boundedStringField(content, "text", CODEX_REALTIME_V3_MAX_TEXT_BYTES);
+      if (textField.oversized) return failure("oversized_field", type);
+      const text = textField.value ?? "";
+      inputBytes += utf8ByteLength(text);
+      if (inputBytes > CODEX_REALTIME_V3_MAX_TEXT_BYTES) {
+        return failure("oversized_field", type);
+      }
+      inputParts.push(text);
+    }
+    const inputTranscript = inputParts.join("");
+    return {
+      ok: true,
+      event: {
+        type,
+        providerEventId,
+        delegationItemId,
+        inputTranscript,
+        offsetMs: finiteNumberField(event, "offset_ms"),
+      },
+    };
+  }
+
+  if (type === "error") {
+    const nested = record(event.error);
+    const message =
+      stringField(event, "message") ??
+      stringField(nested, "message") ??
+      (event.error === undefined ? undefined : JSON.stringify(event.error));
+    if (message === undefined) return failure("invalid_shape", type);
+    if (utf8ByteLength(message) > CODEX_REALTIME_V3_MAX_TEXT_BYTES) {
+      return failure("oversized_field", type);
+    }
+    return { ok: true, event: { type, providerEventId, message } };
+  }
+
+  return failure("unsupported_type", type);
+}
+
+export function encodeCodexRealtimeV3DelegationContextAppend(input: {
+  delegationItemId: string;
+  text: string;
+  channel?: CodexRealtimeV3ContextAppendChannel | undefined;
+}): CodexRealtimeV3DelegationContextAppend[] {
+  return contextAppendChunks(input.text).map((text) => ({
+    type: "delegation.context.append",
+    delegation_item_id: input.delegationItemId,
+    ...(input.channel ? { channel: input.channel } : {}),
+    content: [{ type: "input_text", text }],
+  }));
+}
+
+export function encodeCodexRealtimeV3SessionContextAppend(input: {
+  text: string;
+  channel?: CodexRealtimeV3ContextAppendChannel | undefined;
+}): CodexRealtimeV3SessionContextAppend[] {
+  return contextAppendChunks(input.text).map((text) => ({
+    type: "session.context.append",
+    ...(input.channel ? { channel: input.channel } : {}),
+    content: [{ type: "input_text", text }],
+  }));
+}
+
+export function contextAppendChunks(text: string): string[] {
+  if (utf8ByteLength(text) <= CODEX_REALTIME_CONTEXT_APPEND_MAX_BYTES) return [text];
+  const chunks: string[] = [];
+  let chunk = "";
+  let bytes = 0;
+  for (const character of text) {
+    const characterBytes = utf8ByteLength(character);
+    if (bytes + characterBytes > CODEX_REALTIME_CONTEXT_APPEND_MAX_BYTES && chunk) {
+      chunks.push(chunk);
+      chunk = "";
+      bytes = 0;
+    }
+    chunk += character;
+    bytes += characterBytes;
+  }
+  if (chunk || text.length === 0) chunks.push(chunk);
+  return chunks;
+}
+
+function utf8ByteLength(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}
+
+function failure(
+  reason: CodexRealtimeV3ParseFailure["reason"],
+  eventType: string | null,
+): CodexRealtimeV3ParseFailure {
+  return { ok: false, reason, eventType };
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function stringField(value: Record<string, unknown>, key: string): string | undefined {
+  return typeof value[key] === "string" ? value[key] : undefined;
+}
+
+function boundedStringField(
+  value: Record<string, unknown>,
+  key: string,
+  maxBytes: number,
+): { value: string | undefined; oversized: boolean } {
+  const candidate = stringField(value, key);
+  return {
+    value: candidate,
+    oversized: candidate !== undefined && utf8ByteLength(candidate) > maxBytes,
+  };
+}
+
+function firstBoundedStringField(
+  value: Record<string, unknown>,
+  keys: readonly string[],
+  maxBytes: number,
+): { value: string | undefined; oversized: boolean } {
+  for (const key of keys) {
+    if (typeof value[key] === "string") return boundedStringField(value, key, maxBytes);
+  }
+  return { value: undefined, oversized: false };
+}
+
+function finiteNumberField(value: Record<string, unknown>, key: string): number | null {
+  const candidate = value[key];
+  return typeof candidate === "number" && Number.isFinite(candidate) ? candidate : null;
+}