@opengeni/sdk 0.36.1 → 0.40.0

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;
@@ -257,10 +461,13 @@ export type RepositoryResourceRef = {
   githubRepositoryId?: number | undefined;
 };
 
+/** Value mirror of `@opengeni/contracts`; parity-tested without adding an SDK runtime dependency. */
+export const DEFAULT_FILE_RESOURCE_MOUNT_ROOT = ".opengeni/files" as const;
+
 export type FileResourceRef = {
   kind: "file";
   fileId: string;
-  /** Optional workspace-relative override; defaults to `files/<file-id>`. */
+  /** Optional workspace-relative override; defaults to `.opengeni/files/<file-id>`. */
   mountPath?: string | undefined;
 };
 
@@ -437,6 +644,22 @@ export type OpenGeniSlackBotInstallStart = {
 export type GoogleDriveTargetScope = "user" | "workspace" | "organization";
 export type GoogleDriveSyncCadence = "manual" | "hourly" | "daily";
 export type GoogleDriveReadPolicy = "allow" | "ask" | "block";
+export type GoogleDriveConnectionLifecycleState =
+  | "active"
+  | "paused"
+  | "token_revoked"
+  | "app_removed"
+  | "disconnected"
+  | "reconnect_required"
+  | "reconsent_required";
+
+export type GoogleDriveConnectionLifecycle =
+  | {
+      state: Exclude<GoogleDriveConnectionLifecycleState, "app_removed">;
+      recoverable: true;
+      observedAt: string;
+    }
+  | { state: "app_removed"; recoverable: false; observedAt: string };
 
 export type GoogleDriveSelectedSource = {
   id: string;
@@ -457,6 +680,7 @@ export type GoogleDriveConnectionMetadata = {
   googleDisplayName: string | null;
   verifiedAt: string;
   accessMode: "metadata_readonly" | "readonly";
+  lifecycle?: GoogleDriveConnectionLifecycle | undefined;
   selectedSources?: GoogleDriveSelectedSource[] | undefined;
   /** @deprecated Read selectedSources; retained while existing connections migrate. */
   selectedSource?: GoogleDriveSelectedSource | null | undefined;
@@ -472,6 +696,16 @@ export type GoogleDriveOAuthStartResponse = {
   expiresAt: string;
 };
 
+export type GoogleDriveLifecycleActionRequest = {
+  action: "pause" | "resume";
+  expectedVersion: number;
+};
+
+export type GoogleDriveDisconnectRequest = {
+  expectedVersion: number;
+  idempotencyKey: string;
+};
+
 export type GoogleDriveBrowseItem = {
   id: string;
   name: string;
@@ -614,6 +848,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[];
@@ -794,8 +1030,6 @@ export type HumanInputQuestion = {
   allowOther: boolean;
   validation?:
     | {
-        minLength?: number | null | undefined;
-        maxLength?: number | null | undefined;
         minSelections?: number | null | undefined;
         maxSelections?: number | null | undefined;
       }
@@ -841,6 +1075,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 +1928,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 +1938,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;
@@ -1892,6 +2132,7 @@ export type ModelCapabilitiesV1 = {
     codeExecution: ModelCapabilityStateV1;
   };
   inputModalities: Array<"text" | "image" | "audio">;
+  inputFileMediaTypes?: string[] | undefined;
   outputModalities: Array<"text" | "image" | "audio">;
   transports: {
     sse: ModelCapabilityStateV1;
@@ -2163,7 +2404,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 +2609,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 +2640,7 @@ export type UpdateWorkspaceSettingsRequest = {
   transcription?: WorkspaceTranscriptionPolicy | undefined;
   maxNestedAgentDepth?: number | null | undefined;
   codexCompactionDefault?: "remote_v2" | "portable" | undefined;
+  slackReactionSummon?: WorkspaceSlackReactionSummonSettings | undefined;
   [key: string]: unknown;
 };
 
@@ -2682,6 +2944,8 @@ export type SessionControlResponse = {
   effectiveControl: EffectiveSessionControl;
   interruptionCount: number;
   wakeCount: number;
+  cancelledSessionCount: number;
+  cancelledTurnCount: number;
 };
 
 export type WorkspaceInferenceControlResponse = {
@@ -3130,6 +3394,8 @@ export type KnowledgeSourceKind =
   | "other";
 export type DocumentSearchMode = "hybrid" | "vector" | "keyword";
 
+export type DocumentAuthorityKind = "organization" | "workspace" | "personal";
+
 export type DocumentVisibility = "workspace" | "private";
 
 export type DocumentCurationStatus = "none" | "pending" | "suggested" | "auto_filed" | "failed";
@@ -3171,6 +3437,9 @@ export type Document = {
   sourceUpdatedAt: string | null;
   sourceVersion: string | null;
   aclTags: string[];
+  authorityKind: DocumentAuthorityKind;
+  authorityWorkspaceId: string | null;
+  authoritySubjectId: string | null;
   visibility: DocumentVisibility;
   createdBy: string | null;
   agentAccess: boolean;
@@ -3205,6 +3474,9 @@ export type DocumentSearchResult = {
   sourceUpdatedAt: string | null;
   sourceVersion: string | null;
   aclTags: string[];
+  authorityKind: DocumentAuthorityKind;
+  authorityWorkspaceId: string | null;
+  authoritySubjectId: string | null;
 };
 
 export type CreateDocumentBaseRequest = {
@@ -3224,6 +3496,7 @@ export type AddDocumentRequest = {
   sourceUpdatedAt?: string | undefined;
   sourceVersion?: string | undefined;
   aclTags?: string[] | undefined;
+  authorityKind?: DocumentAuthorityKind | undefined;
   visibility?: DocumentVisibility | undefined;
   agentAccess?: boolean | undefined;
 };
@@ -3233,6 +3506,7 @@ export type CreateKnowledgeDropRequest = {
   fileId?: string | undefined;
   filename?: string | undefined;
   title?: string | undefined;
+  authorityKind?: DocumentAuthorityKind | undefined;
   visibility?: DocumentVisibility | undefined;
   agentAccess?: boolean | undefined;
 };

package/src/workspace-instruction-policies.ts

@@ -29,6 +29,7 @@ export type WorkspaceInstructionPolicyRevisionIdentity = {
 
 export type WorkspaceInstructionPolicyRevision = WorkspaceInstructionPolicyRevisionIdentity &
   WorkspaceInstructionPolicyTarget & {
+    operationId: string;
     accountId: string;
     workspaceId: string;
     content: string;
@@ -52,6 +53,7 @@ export type WorkspaceInstructionPolicyHead = WorkspaceInstructionPolicyTarget &
 
 export type WorkspaceInstructionPolicyActivationEvent = WorkspaceInstructionPolicyTarget & {
   id: string;
+  operationId: string;
   accountId: string;
   workspaceId: string;
   type: WorkspaceInstructionPolicyActivationType;
@@ -64,6 +66,7 @@ export type WorkspaceInstructionPolicyActivationEvent = WorkspaceInstructionPoli
 };
 
 export type CreateWorkspaceInstructionPolicyDraftRequest = WorkspaceInstructionPolicyTarget & {
+  operationId?: string;
   content: string;
   provenanceSource?: WorkspaceInstructionPolicyDraftProvenanceSource;
   provenanceSourceId?: string | null;
@@ -71,6 +74,7 @@ export type CreateWorkspaceInstructionPolicyDraftRequest = WorkspaceInstructionP
 };
 
 export type ImportLegacyWorkspaceInstructionPolicyDraftRequest = {
+  operationId?: string;
   supersedesRevisionId?: string | null;
 };
 
@@ -102,13 +106,17 @@ export type WorkspaceInstructionPolicyDiffResponse = {
 };
 
 export type ActivateWorkspaceInstructionPolicyRequest = {
+  operationId?: string;
   expectedCurrentRevisionId: string | null;
+  expectedActivationVersion?: number;
   reason: string;
 };
 
 export type RollbackWorkspaceInstructionPolicyRequest = {
+  operationId?: string;
   targetRevisionId: string;
   expectedCurrentRevisionId: string;
+  expectedActivationVersion?: number;
   reason: string;
 };
 
@@ -122,3 +130,8 @@ export type WorkspaceInstructionPolicyConflictResponse = {
   message: string;
   currentHead: WorkspaceInstructionPolicyHead | null;
 };
+
+export type WorkspaceInstructionPolicyOperationReuseResponse = {
+  code: "WORKSPACE_INSTRUCTION_POLICY_OPERATION_REUSED";
+  message: string;
+};

package/src/workspace-state.ts

@@ -49,15 +49,93 @@ export type WorkspaceStateGapCode =
   | "pending_memory_review"
   | "partial_inventory";
 
+export type WorkspaceStateGovernanceDriftStatus =
+  | "identical"
+  | "changed"
+  | "superseded"
+  | "missing"
+  | "unavailable"
+  | "truncated";
+
+export type WorkspaceStateGetOptions = { attemptId?: string };
+
+export type WorkspaceStateAttemptGovernance =
+  | { status: "not_requested" }
+  | {
+      status: "unavailable";
+      reason: "attempt_not_found_or_not_authorized";
+      driftStatus: "unavailable";
+    }
+  | {
+      status: "available";
+      attemptId: string;
+      executionGeneration: number;
+      acceptedAt: string;
+      policySnapshot:
+        | { status: "missing" }
+        | {
+            status: "available";
+            id: string;
+            createdAt: string;
+            entryHash: string;
+            policyRole: string | null;
+            roleSource:
+              | "session_binding"
+              | "metadata_fallback"
+              | "none"
+              | "invalid_metadata_fallback";
+            entries: Array<{
+              kind: WorkspaceInstructionPolicyKind;
+              scope: WorkspaceInstructionPolicyScope;
+              roleKey: string | null;
+              revisionId: string;
+              revision: number;
+              contentHash: string;
+              activationVersion: number;
+              activatedAt: string;
+              provenance: {
+                source: WorkspaceInstructionPolicyProvenanceSource;
+                sourceIdHash: string | null;
+              };
+            }>;
+          };
+      preferenceSnapshot:
+        | { status: "missing" }
+        | {
+            status: "available";
+            id: string;
+            createdAt: string;
+            descriptorHash: string;
+            descriptorCount: number;
+            truncated: boolean;
+          };
+      drift: {
+        overall: WorkspaceStateGovernanceDriftStatus;
+        policy: {
+          status: WorkspaceStateGovernanceDriftStatus;
+          snapshotHash: string | null;
+          currentHash: string | null;
+          snapshotTargetCount: number;
+          currentTargetCount: number;
+        };
+        preferences: {
+          status: WorkspaceStateGovernanceDriftStatus;
+          snapshotHash: string | null;
+          currentHash: string | null;
+          snapshotDescriptorCount: number;
+          currentDescriptorCount: number;
+          snapshotTruncated: boolean;
+          currentTruncated: boolean;
+        };
+      };
+    };
+
 export type WorkspaceStateResponse = {
   workspaceId: string;
   generatedAt: string;
   truth: {
     current: { source: "read_time_projection"; capturedAt: string };
-    policySnapshot: {
-      status: "not_captured";
-      reason: "workspace_instruction_policy_snapshot_not_implemented";
-    };
+    attemptGovernance: WorkspaceStateAttemptGovernance;
   };
   policy: {
     authority: "workspace_instruction_policy_heads";