@opengeni/sdk 0.36.1 → 0.37.0

package/src/index.ts

@@ -27,6 +27,56 @@ export { parseSseStream } from "./sse";
 export type { SseMessage } from "./sse";
 export { normalizeMcpOutput } from "./mcp-output";
 export type { NormalizedMcpOutput } from "./mcp-output";
+export {
+  CodexRealtimeMicrophoneError,
+  acquireCodexRealtimeMicrophone,
+  codexRealtimeMicrophoneHealthy,
+  startCodexRealtimeWebrtc,
+} from "./codex-realtime";
+export type {
+  AcquireCodexRealtimeMicrophoneOptions,
+  CodexRealtimeAudibleOutputState,
+  CodexRealtimeConnectionHealth,
+  CodexRealtimeMicrophoneErrorCode,
+  CodexRealtimeNegotiator,
+  CodexRealtimeWebrtcSession,
+  StartCodexRealtimeWebrtcOptions,
+} from "./codex-realtime";
+export {
+  CODEX_REALTIME_CONTEXT_APPEND_MAX_BYTES,
+  contextAppendChunks,
+  createCodexRealtimeV3Bridge,
+  encodeCodexRealtimeV3DelegationContextAppend,
+  encodeCodexRealtimeV3SessionContextAppend,
+  parseCodexRealtimeV3Event,
+} from "./codex-realtime-v3";
+export type {
+  CodexRealtimeV3Bridge,
+  CodexRealtimeV3BridgeOptions,
+  CodexRealtimeV3BridgeSnapshot,
+  CodexRealtimeV3ContextAppendChannel,
+  CodexRealtimeV3DelegationContextAppend,
+  CodexRealtimeV3Event,
+  CodexRealtimeV3ParseFailure,
+  CodexRealtimeV3ParseResult,
+  CodexRealtimeV3SessionContextAppend,
+} from "./codex-realtime-v3";
+export { createCodexRealtimeController } from "./codex-realtime-controller";
+export type {
+  CodexRealtimeController,
+  CodexRealtimeControllerClient,
+  CodexRealtimeDiagnostic,
+  CodexRealtimeDiagnosticKind,
+  CodexRealtimeControllerSnapshot,
+  CodexRealtimeControllerStatus,
+  CodexRealtimeMicrophoneState,
+  CodexRealtimeOwnerStorage,
+  CreateCodexRealtimeControllerOptions,
+  RealtimeControllerTransportStarter,
+} from "./codex-realtime-controller";
+export { createGatewayRealtimeTransportStarter } from "./gateway-realtime-transport";
+export { projectSessionRealtimeLifecycle } from "./codex-realtime-lifecycle";
+export type { SessionRealtimeLifecycleProjection } from "./codex-realtime-lifecycle";
 // Desktop (noVNC) transport contract — pure, zero-dep (the RFB import lives in
 // @opengeni/react). URL assembler + connection state machine + rotation fence.
 export { desktopSocketUrl, nextDesktopState, applyUrlRotation } from "./desktop";
@@ -169,10 +219,12 @@ export {
 } from "./types";
 export type {
   AccessContext,
+  ActivateCodexRealtimeConnectionRequest,
   AccessGrant,
   AccountGrant,
   AccountRole,
   AddWorkspaceMemberRequest,
+  BeginSessionRealtimeRequest,
   AgentMessageCompletedPayload,
   AgentTextDeltaPayload,
   AgentToolCallCreatedPayload,
@@ -215,6 +267,14 @@ export type {
   ClientConfig,
   ClientVoiceInputConfig,
   ClientModel,
+  CodexRealtimeVoice,
+  CodexRealtimeWebrtcRequest,
+  CodexRealtimeWebrtcResponse,
+  CodexRealtimeWebrtcVersion,
+  GatewayRealtimeConnectRequest,
+  GatewayRealtimeConnectResponse,
+  GatewayRealtimeInitialItem,
+  EndSessionRealtimeRequest,
   ModelAvailabilityV1,
   ModelBillingAttributionV1,
   ModelCapabilitiesV1,
@@ -224,8 +284,16 @@ export type {
   ModelCredentialSourceV1,
   ModelPricingScheduleV1,
   ModelPricingV1,
+  RenewSessionRealtimeRequest,
+  SessionRealtimeEndReason,
+  SessionRealtimeMode,
+  SessionRealtimeModel,
+  SessionRealtimeMutationResponse,
+  SessionRealtimeState,
   WorkspaceModelCatalogModel,
   WorkspaceModelCatalogResponse,
+  WorkspaceRealtimeModelCatalogItem,
+  WorkspaceRealtimeModelCatalogResponse,
   CodexAccount,
   CodexAccountOverview,
   CodexAccountsResponse,
@@ -261,6 +329,8 @@ export type {
   CreateCapabilityCatalogItemRequest,
   OpenGeniSlackBotInstallRequest,
   OpenGeniSlackBotInstallStart,
+  SlackReactionChannel,
+  SlackReactionChannelListResponse,
   CreateConnectionRequest,
   CreateCheckoutRequest,
   CreateCheckoutResponse,
@@ -535,6 +605,7 @@ export type {
   UpdateWorkspaceMemberRequest,
   UpdateWorkspaceRequest,
   UpdateWorkspaceSettingsRequest,
+  WorkspaceSlackReactionSummonSettings,
   TranscribeAudioResponse,
   UploadFileInput,
   UsageEvent,

package/src/types.ts

@@ -5,6 +5,210 @@ import type { WorkspaceTranscriptionPolicy } from "./transcription";
 // publishable on its own; `test/contract-parity.test.ts` pins these types to
 // the contracts package so drift fails the gate instead of shipping.
 
+export type CodexRealtimeWebrtcVersion = "v3";
+export type CodexRealtimeVoice =
+  | "juniper"
+  | "maple"
+  | "spruce"
+  | "ember"
+  | "vale"
+  | "breeze"
+  | "arbor"
+  | "sol"
+  | "cove";
+
+export type CodexRealtimeWebrtcRequest = {
+  realtimeId: string;
+  operationId: string;
+  browserInstanceId: string;
+  ownerKey: string;
+  expectedVersion: number;
+  expectedConnectionEpoch: number;
+  rotate: boolean;
+  browserActivation?: "required" | undefined;
+  sdp: string;
+  version: CodexRealtimeWebrtcVersion;
+  instructions?: string | undefined;
+  voice?: CodexRealtimeVoice | undefined;
+};
+
+export type CodexRealtimeWebrtcResponse = {
+  sdp: string;
+  version: CodexRealtimeWebrtcVersion;
+  model: "gpt-live-1-boulder-alpha";
+  connectionId: string;
+  connectionEpoch: number;
+  startupFenceSequence: number;
+  modeVersion: number;
+  replay: boolean;
+};
+
+export type GatewayRealtimeConnectRequest = {
+  realtimeId: string;
+  operationId: string;
+  browserInstanceId: string;
+  ownerKey: string;
+  expectedVersion: number;
+  expectedConnectionEpoch: number;
+  rotate: boolean;
+};
+
+export type GatewayRealtimeInitialItem = {
+  role: "user" | "developer" | "assistant";
+  text: string;
+};
+
+export type GatewayRealtimeConnectResponse = {
+  token: string;
+  url: string;
+  upstreamModelId: string;
+  expiresAt: number | null;
+  connectionId: string;
+  connectionEpoch: number;
+  startupFenceSequence: number;
+  modeVersion: number;
+  initialItems: GatewayRealtimeInitialItem[];
+  instructions: string;
+  replay: false;
+};
+
+export type ActivateCodexRealtimeConnectionRequest = {
+  operationId: string;
+  browserInstanceId: string;
+  ownerKey: string;
+  connectionEpoch: number;
+  expectedVersion: number;
+  expectedConnectionEpoch: number;
+};
+
+export type SessionRealtimeLedgerDirection = "provider_in" | "provider_out";
+export type SessionRealtimeLedgerKind =
+  | "user_transcript"
+  | "assistant_transcript"
+  | "delegation_call"
+  | "delegation_progress"
+  | "delegation_result"
+  | "interruption"
+  | "session_update"
+  | "error";
+
+export type SessionRealtimeLedgerEntry = {
+  id: string;
+  realtimeId: string;
+  operationId: string;
+  connectionEpoch: number;
+  sequence: number;
+  direction: SessionRealtimeLedgerDirection;
+  kind: SessionRealtimeLedgerKind;
+  role: "user" | "assistant" | null;
+  providerEventId: string | null;
+  delegationItemId: string | null;
+  sourceUpdateId: string | null;
+  historyItemId: string | null;
+  turnId: string | null;
+  text: string | null;
+  payload: Record<string, unknown>;
+  clientAckedAt: string | null;
+  providerAckedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type SessionRealtimeInboundEntry = {
+  operationId: string;
+  kind: Exclude<
+    SessionRealtimeLedgerKind,
+    "delegation_progress" | "delegation_result" | "session_update"
+  >;
+  role?: "user" | "assistant" | null | undefined;
+  providerEventId?: string | null | undefined;
+  delegationItemId?: string | null | undefined;
+  text?: string | null | undefined;
+  payload?: Record<string, unknown> | undefined;
+};
+
+export type SyncSessionRealtimeLedgerRequest = {
+  browserInstanceId: string;
+  ownerKey: string;
+  expectedVersion: number;
+  connectionId: string;
+  connectionEpoch: number;
+  entries?: SessionRealtimeInboundEntry[] | undefined;
+  clientAckThroughSequence?: number | null | undefined;
+  providerAckSequences?: number[] | undefined;
+  providerStarted?:
+    | { providerSessionId: string; providerEventId?: string | null | undefined }
+    | undefined;
+};
+
+export type SyncSessionRealtimeLedgerResponse = {
+  accepted: Array<{ entry: SessionRealtimeLedgerEntry; replay: boolean }>;
+  outbound: SessionRealtimeLedgerEntry[];
+};
+
+export type SessionRealtimeModel =
+  | "gpt-live-1-boulder-alpha"
+  | "opengeni-gateway/openai/gpt-realtime-2.1"
+  | "opengeni-gateway/openai/gpt-realtime-mini"
+  | "opengeni-gateway/xai/grok-voice-think-fast-2.0"
+  | "workspace-gateway/openai/gpt-realtime-2.1"
+  | "workspace-gateway/openai/gpt-realtime-mini"
+  | "workspace-gateway/xai/grok-voice-think-fast-2.0";
+
+export type WorkspaceRealtimeModelCatalogItem = {
+  id: SessionRealtimeModel;
+  label: string;
+  provider: "OpenGeni" | "Connected Codex" | "Your Gateway";
+  description: string;
+  available: boolean;
+  unavailableReason: string | null;
+  recommended: boolean;
+};
+
+export type WorkspaceRealtimeModelCatalogResponse = {
+  models: WorkspaceRealtimeModelCatalogItem[];
+};
+export type SessionRealtimeState = "active" | "ended";
+export type SessionRealtimeEndReason = "user_stop" | "browser_unload" | "lease_expired";
+
+export type SessionRealtimeMode = {
+  id: string;
+  sessionId: string;
+  operationId: string;
+  browserInstanceId: string;
+  model: SessionRealtimeModel;
+  state: SessionRealtimeState;
+  version: number;
+  connectionEpoch: number;
+  leaseExpiresAt: string;
+  lastHeartbeatAt: string;
+  startedAt: string;
+  endedAt: string | null;
+  endReason: SessionRealtimeEndReason | null;
+};
+
+export type BeginSessionRealtimeRequest = {
+  operationId: string;
+  browserInstanceId: string;
+  ownerKey: string;
+  model: SessionRealtimeModel;
+};
+
+export type RenewSessionRealtimeRequest = {
+  browserInstanceId: string;
+  ownerKey: string;
+  expectedVersion: number;
+};
+
+export type EndSessionRealtimeRequest = RenewSessionRealtimeRequest & {
+  reason: Extract<SessionRealtimeEndReason, "user_stop" | "browser_unload">;
+};
+
+export type SessionRealtimeMutationResponse = {
+  mode: SessionRealtimeMode;
+  replay: boolean;
+};
+
 export type SessionStatus =
   | "queued"
   | "running"
@@ -228,7 +432,7 @@ export type AcknowledgeStreamResponse = {
 export type ViewerHeartbeatRequest = { leaseEpoch: number };
 export type ViewerHeartbeatResponse = { alive: boolean };
 
-export type ReasoningEffort = "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+export type ReasoningEffort = "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 export type LatencyMode = "standard" | "priority" | "fast";
 export type GitCredentialProvider = "github" | "gitlab" | "azure_devops";
 export type GitCredentialBindingId = string;
@@ -614,6 +818,8 @@ export type Session = {
   // Per-session agent persona/system instructions supplied at create; null when
   // the session carried none. Org-visible metadata, never a timeline event.
   instructions: string | null;
+  /** Immutable normalized prompt-policy role; distinct from membership roles. */
+  policyRole: string | null;
   resources: ResourceRef[];
   skills: SessionSkill[];
   tools: ToolRef[];
@@ -841,6 +1047,8 @@ export const SESSION_EVENT_TYPES = [
   // Defensive bounded projection for malformed/legacy oversized envelopes.
   "session.event.envelope_omitted",
   "session.status.changed",
+  "session.realtime.started",
+  "session.realtime.ended",
   "session.requiresAction",
   "session.humanInput.requested",
   "session.context.compaction.requested",
@@ -1692,7 +1900,9 @@ export type CreateSessionRequest = {
   // projection before OpenGeni admits the initial turn. Replays must retain the
   // same UUID and idempotency key.
   requestedSessionId?: string | undefined;
-  initialMessage: string;
+  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;
   // Per-session agent persona/system instructions (org-visible metadata, not a
@@ -1700,6 +1910,8 @@ export type CreateSessionRequest = {
   // how a host supplies per-agent-type prompts without leaking them into the
   // user-visible timeline. Trimmed, non-empty, max 32768 chars.
   instructions?: string | undefined;
+  /** Immutable normalized prompt-policy role; distinct from membership roles. */
+  policyRole?: string | undefined;
   resources?: ResourceRef[] | undefined;
   /** Inline skills fixed onto this session; omitted children inherit them. */
   skills?: SessionSkill[] | undefined;
@@ -2163,7 +2375,9 @@ export type CodexAccountOverview = {
 };
 
 /** Independently settled live overview keyed by workspace credential id. */
-export type CodexOverviewResponse = { accounts: Record<string, CodexAccountOverview> };
+export type CodexOverviewResponse = {
+  accounts: Record<string, CodexAccountOverview>;
+};
 
 export type CodexAllocatorUpdate = {
   allocatorEnabled: boolean;
@@ -2366,9 +2580,27 @@ export type WorkspaceSettings = {
   maxNestedAgentDepth?: number | null | undefined;
   /** Default for new Codex sessions; absent ⇒ remote_v2. */
   codexCompactionDefault?: "remote_v2" | "portable" | undefined;
+  slackReactionSummon?: WorkspaceSlackReactionSummonSettings | undefined;
   [key: string]: unknown;
 };
 
+export type WorkspaceSlackReactionSummonSettings = {
+  enabled: boolean;
+  emoji: string;
+  channelPolicy: { mode: "bot_member" } | { mode: "allowlist"; channelIds: string[] };
+};
+
+export type SlackReactionChannel = {
+  id: string;
+  name: string | null;
+  isPrivate: boolean;
+};
+
+export type SlackReactionChannelListResponse = {
+  channels: SlackReactionChannel[];
+  nextCursor: string | null;
+};
+
 export type WorkspaceVoiceInputSettings = {
   enabled: boolean;
 };
@@ -2379,6 +2611,7 @@ export type UpdateWorkspaceSettingsRequest = {
   transcription?: WorkspaceTranscriptionPolicy | undefined;
   maxNestedAgentDepth?: number | null | undefined;
   codexCompactionDefault?: "remote_v2" | "portable" | undefined;
+  slackReactionSummon?: WorkspaceSlackReactionSummonSettings | undefined;
   [key: string]: unknown;
 };
 
@@ -2682,6 +2915,8 @@ export type SessionControlResponse = {
   effectiveControl: EffectiveSessionControl;
   interruptionCount: number;
   wakeCount: number;
+  cancelledSessionCount: number;
+  cancelledTurnCount: number;
 };
 
 export type WorkspaceInferenceControlResponse = {