@opengeni/sdk 0.57.0 → 1.0.1

package/dist/client.d.ts

@@ -32,8 +32,8 @@ export type OpenGeniRequestOptions = {
 export type SendMessageInput = {
     text: string;
     annotations?: SubmittedTimelineAnnotation[];
-    /** System instructions scoped to this exact turn; never visible timeline text. */
-    turnInstructions?: string;
+    /** Model-visible application context attached to this exact user message; omitted by standard timeline rendering. */
+    modelContext?: string;
     resources?: ResourceRef[];
     tools?: ToolRef[];
     model?: string;

package/dist/codex-realtime-controller.d.ts

@@ -83,6 +83,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: {
     client: CodexRealtimeControllerClient;

package/dist/codex-realtime-controller.js

@@ -5,7 +5,7 @@ import {
   projectSessionRealtimeLifecycle,
   sessionRealtimeOwnerStorageKey,
   sessionRealtimeOwnerStorageNamespace
-} from "./chunk-JDLDDRNE.js";
+} from "./chunk-A5DC5WEM.js";
 import "./chunk-GU6JF75T.js";
 export {
   CODEX_REALTIME_NEGOTIATION_TIMEOUT_MS,

package/dist/codex-realtime-v3.d.ts

@@ -1,11 +1,11 @@
-import type { SyncSessionRealtimeLedgerRequest, SyncSessionRealtimeLedgerResponse } from "./types.js";
+import type { SessionRealtimeInboundEntry, SyncSessionRealtimeLedgerRequest, SyncSessionRealtimeLedgerResponse } from "./types.js";
 export { CODEX_REALTIME_CONTEXT_APPEND_MAX_BYTES, CODEX_REALTIME_V3_MAX_EVENT_BYTES, CODEX_REALTIME_V3_MAX_IDENTIFIER_BYTES, CODEX_REALTIME_V3_MAX_TEXT_BYTES, contextAppendChunks, encodeCodexRealtimeV3DelegationContextAppend, encodeCodexRealtimeV3SessionContextAppend, parseCodexRealtimeV3Event, } from "./codex-realtime-v3-wire.js";
 export type { CodexRealtimeV3ContextAppendChannel, CodexRealtimeV3DelegationContextAppend, CodexRealtimeV3Event, CodexRealtimeV3ParseFailure, CodexRealtimeV3ParseResult, CodexRealtimeV3SessionContextAppend, } from "./codex-realtime-v3-wire.js";
 export declare const CODEX_REALTIME_V3_SYNC_MAX_ENTRIES = 64;
 export declare const CODEX_REALTIME_V3_PENDING_MAX_ENTRIES = 256;
 export declare const CODEX_REALTIME_V3_PENDING_MAX_BYTES: number;
 export type CodexRealtimeV3BridgeFatal = {
-    code: "pending_overflow";
+    code: "pending_overflow" | "replay_journal_failed";
     message: string;
 };
 export type CodexRealtimeV3BridgeSnapshot = {
@@ -35,6 +35,17 @@ export type CodexRealtimeV3BridgeOptions = {
     owner: Pick<SyncSessionRealtimeLedgerRequest, "browserInstanceId" | "ownerKey" | "expectedVersion">;
     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;

package/dist/core.js

@@ -3,11 +3,11 @@ import {
 } from "./chunk-VYCTL62C.js";
 import {
   OpenGeniClient
-} from "./chunk-PKQ377ED.js";
+} from "./chunk-YGH5P47G.js";
 import {
   OPENGENI_API_CONTRACT_HEADER,
   OPENGENI_API_CONTRACT_REVISION
-} from "./chunk-HJ3HHUT5.js";
+} from "./chunk-4DV37UUA.js";
 import {
   OpenGeniApiContractMismatchError,
   OpenGeniApiError,

package/dist/editable-artifacts.js

@@ -1,7 +1,7 @@
 import {
   OPENGENI_API_CONTRACT_HEADER,
   OPENGENI_API_CONTRACT_REVISION
-} from "./chunk-HJ3HHUT5.js";
+} from "./chunk-4DV37UUA.js";
 import {
   DEFAULT_ARTIFACT_WORKER_RPC_LIMITS,
   decodeArtifactWorkerRpcMessage,

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   OpenGeniClient
-} from "./chunk-JRPFWI6T.js";
+} from "./chunk-TYZ4JL4J.js";
 import {
   DEFAULT_WORKSPACE_TRANSCRIPTION_POLICY,
   authorizeTranscriptionAdapter,
@@ -21,7 +21,7 @@ import {
   streamWorkspaceControlEvents,
   streamWorkspaceInteractionRevisions,
   streamWorkspaceLiveEvents
-} from "./chunk-PKQ377ED.js";
+} from "./chunk-YGH5P47G.js";
 import {
   DEFAULT_FILE_RESOURCE_MOUNT_ROOT,
   GENERATED_VIDEO_MAX_BYTES,
@@ -33,7 +33,7 @@ import {
   RETAINED_OUTPUT_DEFAULT_PAGE_BYTES,
   RETAINED_OUTPUT_MAX_PAGE_BYTES,
   SESSION_EVENT_TYPES
-} from "./chunk-HJ3HHUT5.js";
+} from "./chunk-4DV37UUA.js";
 import {
   createGatewayRealtimeTransportStarter,
   createXaiSubscriptionRealtimeTransportStarter
@@ -51,7 +51,7 @@ import {
   parseCodexRealtimeV3Event,
   projectSessionRealtimeLifecycle,
   startCodexRealtimeWebrtc
-} from "./chunk-JDLDDRNE.js";
+} from "./chunk-A5DC5WEM.js";
 import {
   OpenGeniApiContractMismatchError,
   OpenGeniApiError,

package/dist/realtime.js

@@ -27,7 +27,7 @@ import {
   sessionRealtimeOwnerStorageKey,
   sessionRealtimeOwnerStorageNamespace,
   startCodexRealtimeWebrtc
-} from "./chunk-JDLDDRNE.js";
+} from "./chunk-A5DC5WEM.js";
 import "./chunk-GU6JF75T.js";
 
 // src/realtime.ts

package/dist/types.d.ts

@@ -90,6 +90,8 @@ export type SessionRealtimeInboundEntry = {
     delegationItemId?: string | null | undefined;
     text?: string | null | undefined;
     payload?: Record<string, unknown> | undefined;
+    /** Model-visible application context attached to this exact realtime message. */
+    modelContext?: string | undefined;
 };
 export type SyncSessionRealtimeLedgerRequest = {
     browserInstanceId: string;
@@ -556,16 +558,25 @@ export type GoogleDriveConnectionMetadata = {
     googleEmail: string;
     googleDisplayName: string | null;
     verifiedAt: string;
-    accessMode: "metadata_readonly" | "readonly";
+    accessMode: "file_only" | "metadata_readonly" | "readonly";
     lifecycle?: GoogleDriveConnectionLifecycle | undefined;
+    outputDestination?: GoogleDriveOutputDestination | undefined;
     documentDestination?: ConnectorDocumentDestination | undefined;
     selectedSources?: GoogleDriveSelectedSource[] | undefined;
     /** @deprecated Read selectedSources; retained while existing connections migrate. */
     selectedSource?: GoogleDriveSelectedSource | null | undefined;
     [key: string]: unknown;
 };
+export type GoogleDriveOutputDestination = {
+    folderId: string;
+    folderName: string;
+    driveId: string | null;
+    location: "my_drive" | "shared_drive";
+    selectedAt: string;
+};
 export type GoogleDriveOAuthStartRequest = {
     connectionId?: string | undefined;
+    capability?: "source_read" | "publish" | undefined;
 };
 export type GoogleDriveOAuthStartResponse = {
     authorizationUrl: string;
@@ -1823,8 +1834,8 @@ export type CreateSessionRequest = {
     initialMessage?: string | undefined;
     /** Create an idle session shell so realtime voice can be the first interaction. */
     startMode?: "realtime" | undefined;
-    /** System instructions scoped to the initial turn; never visible timeline text. */
-    turnInstructions?: string | undefined;
+    /** Model-visible application context attached to the initial user message; omitted by standard timeline rendering. */
+    modelContext?: string | undefined;
     instructions?: string | undefined;
     /** Immutable normalized prompt-policy role; distinct from membership roles. */
     policyRole?: string | undefined;
@@ -2288,7 +2299,7 @@ export type ClientAuthConfig = {
     mode: "managedSession";
     session: "cookie";
 };
-export declare const OPENGENI_API_CONTRACT_REVISION: "2026-08-social-provider-tools-v1";
+export declare const OPENGENI_API_CONTRACT_REVISION: "2026-08-model-context-v1";
 export declare const OPENGENI_API_CONTRACT_HEADER: "x-opengeni-api-contract";
 /** Bounded request/response identifier shared by browser, ingress, and API diagnostics. */
 export declare const OPENGENI_CORRELATION_HEADER: "x-opengeni-correlation-id";
@@ -4784,7 +4795,7 @@ export type UserMessageEventInput = {
     payload: {
         text: string;
         annotations?: SubmittedTimelineAnnotation[] | undefined;
-        turnInstructions?: string | undefined;
+        modelContext?: string | undefined;
         resources?: ResourceRef[] | undefined;
         model?: string | undefined;
         reasoningEffort?: ReasoningEffort | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/sdk",
-  "version": "0.57.0",
+  "version": "1.0.1",
   "description": "Framework-agnostic TypeScript SDK for the OpenGeni API: typed client, session lifecycle, SSE event streaming with reconnect + replay-by-sequence, and proxy re-streaming helpers.",
   "license": "Apache-2.0",
   "repository": {
@@ -73,7 +73,7 @@
     "prepublishOnly": "bash ../../scripts/prepublish-guard"
   },
   "dependencies": {
-    "@opengeni/contracts": "^0.50.0"
+    "@opengeni/contracts": "^1.0.1"
   },
   "engines": {
     "node": ">=18"

package/src/client.ts

@@ -493,8 +493,8 @@ export type OpenGeniRequestOptions = {
 export type SendMessageInput = {
   text: string;
   annotations?: SubmittedTimelineAnnotation[];
-  /** System instructions scoped to this exact turn; never visible timeline text. */
-  turnInstructions?: string;
+  /** Model-visible application context attached to this exact user message; omitted by standard timeline rendering. */
+  modelContext?: string;
   resources?: ResourceRef[];
   tools?: ToolRef[];
   model?: string;

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"
@@ -213,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: {
@@ -258,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 = {
@@ -338,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 };
@@ -422,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 => {
@@ -524,7 +610,10 @@ export function createCodexRealtimeController(
       });
       return;
     }
-    publish({ audibleOutput: next, ...(next === "audible" ? { error: null } : {}) });
+    publish({
+      audibleOutput: next,
+      ...(next === "audible" ? { error: null } : {}),
+    });
   };
 
   const startActiveIntervals = (): void => {
@@ -911,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 });
         },
@@ -1097,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;
       }
@@ -1173,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) => {
@@ -1377,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 ||
@@ -1386,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;
 }