@opengeni/sdk 0.48.0 → 0.57.0

package/src/codex-realtime-controller.ts

@@ -123,6 +123,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 +155,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. */
@@ -454,16 +462,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;
     }
   };
 

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/company-profile.ts

@@ -0,0 +1,92 @@
+export const COMPANY_PROFILE_SCALAR_MAX_CHARS = 2_048;
+export const COMPANY_PROFILE_ENTRY_MAX_CHARS = 1_024;
+export const COMPANY_PROFILE_ENTRY_MAX_COUNT = 16;
+
+export type CompanyProfileEntry = { key: string; content: string };
+export type CompanyProfileContent = {
+  identity: string | null;
+  mission: string | null;
+  products: CompanyProfileEntry[];
+  customers: CompanyProfileEntry[];
+  goals: CompanyProfileEntry[];
+  constraints: CompanyProfileEntry[];
+};
+export type CompanyProfileRevisionIdentity = {
+  id: string;
+  revision: number;
+  contentHash: string;
+};
+export type CompanyProfileRevision = CompanyProfileRevisionIdentity & {
+  operationId: string;
+  accountId: string;
+  intent: "active" | "proposal";
+  profile: CompanyProfileContent;
+  provenance: { source: "human" | "durable_learning" | "migration"; sourceId: string | null };
+  supersedesRevisionId: string | null;
+  createdBySubjectId: string;
+  createdAt: string;
+};
+export type CompanyProfileHead = {
+  accountId: string;
+  revisionId: string;
+  revision: number;
+  contentHash: string;
+  activationVersion: number;
+  activatedAt: string;
+};
+export type CompanyProfileActivationEvent = {
+  id: string;
+  operationId: string;
+  accountId: string;
+  type: "activate" | "rollback";
+  activationVersion: number;
+  oldRevision: CompanyProfileRevisionIdentity | null;
+  newRevision: CompanyProfileRevisionIdentity | null;
+  actorSubjectId: string;
+  reason: string;
+  createdAt: string;
+};
+export type CompanyProfileListOptions = { afterRevision?: number; limit?: number };
+export type CompanyProfileListResponse = {
+  current: CompanyProfileHead | null;
+  activeRevision: CompanyProfileRevision | null;
+  revisions: CompanyProfileRevision[];
+  activationEvents: CompanyProfileActivationEvent[];
+  nextAfterRevision: number | null;
+};
+export type UpdateCompanyProfileRequest = {
+  operationId?: string;
+  profile: CompanyProfileContent;
+  expectedCurrentRevisionId: string | null;
+  expectedActivationVersion: number;
+  reason: string;
+};
+export type ActivateCompanyProfileRevisionRequest = {
+  operationId?: string;
+  expectedCurrentRevisionId: string | null;
+  expectedActivationVersion: number;
+  reason: string;
+};
+export type RollbackCompanyProfileRequest = {
+  operationId?: string;
+  targetRevisionId: string;
+  expectedCurrentRevisionId: string;
+  expectedActivationVersion: number;
+  reason: string;
+};
+export type CompanyProfileMutationResponse = {
+  revision: CompanyProfileRevision | null;
+  head: CompanyProfileHead | null;
+  event: CompanyProfileActivationEvent | null;
+};
+export type CompanyProfileDiffRequest = { fromRevisionId: string; toRevisionId: string };
+export type CompanyProfileDiffResponse = {
+  from: CompanyProfileRevision;
+  to: CompanyProfileRevision;
+  format: "unified_json";
+  diff: string;
+};
+
+export function normalizeCompanyProfileStableKey(value: string): string {
+  return value.normalize("NFKC").trim().toLowerCase().replace(/\s+/gu, "-").replace(/-+/g, "-");
+}

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 =

package/src/editable-artifact-resources.ts

@@ -0,0 +1,119 @@
+import type { OpenGeniRequestOptions } from "./client";
+import type { EditableArtifactModality } from "./editable-artifacts/types";
+
+/** Durable metadata returned by the editable-artifact product API. */
+export type EditableArtifactResource = Readonly<{
+  id: string;
+  modality: EditableArtifactModality;
+  title: string;
+  lifecycle: "active" | "archived";
+  headSequence: number;
+  stateHash: string;
+  createdAt: string;
+  updatedAt: string;
+}>;
+
+export type EditableArtifactListResource = Readonly<{
+  artifacts: readonly EditableArtifactResource[];
+}>;
+
+export type CreateEditableArtifactResourceRequest = Readonly<{
+  /** Stable across transport retries; conflicting reuse is rejected. */
+  idempotencyKey: string;
+  /** Exact writer replica that will open the first live editing session. */
+  replicaId: string;
+  modality: EditableArtifactModality;
+  title: string;
+}>;
+
+export type ImportEditableArtifactResourceRequest = Readonly<{
+  idempotencyKey: string;
+  replicaId: string;
+  modality: EditableArtifactModality;
+  title: string;
+  sourceFileId: string;
+}>;
+
+export type ReadEditableArtifactResourceOptions = OpenGeniRequestOptions &
+  Readonly<{
+    /** Writer/read replica used to mint artifact-scoped authority. */
+    replicaId: string;
+  }>;
+
+export type ListSessionEditableArtifactResourcesOptions = OpenGeniRequestOptions &
+  Readonly<{
+    replicaId: string;
+  }>;
+
+export type EditableArtifactMaterializationFormat =
+  | "xlsx"
+  | "pptx"
+  | "docx"
+  | "pdf"
+  | "png"
+  | "webp";
+
+export type EditableArtifactPinnedVersionResource = Readonly<{
+  id: string;
+  artifactId: string;
+  modality: EditableArtifactModality;
+  snapshotId: string;
+  headSequence: number;
+  causalFrontier: readonly Readonly<{ replicaId: string; counter: number }>[] | null;
+  nativeRevision: number | null;
+  stateHash: string;
+  name: string;
+  pinned: true;
+  createdAt: string;
+  replayed: boolean;
+}>;
+
+export type PinEditableArtifactVersionRequest = Readonly<{
+  replicaId: string;
+  idempotencyKey: string;
+  name: string;
+}>;
+
+export type EditableArtifactMaterializationResultResource = Readonly<{
+  id: string;
+  byteSize: number;
+  contentHash: string;
+  mimeType:
+    | "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+    | "application/vnd.openxmlformats-officedocument.presentationml.presentation"
+    | "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+    | "application/pdf"
+    | "image/png"
+    | "image/webp";
+  verifiedAt: string;
+  createdAt: string;
+}>;
+
+export type EditableArtifactMaterializationJobResource = Readonly<{
+  id: string;
+  artifactId: string;
+  versionId: string;
+  inputSnapshotId: string;
+  targetHeadSequence: number;
+  stateHash: string;
+  format: EditableArtifactMaterializationFormat;
+  state: "pending" | "running" | "succeeded" | "failed";
+  attemptCount: number;
+  errorCode: string | null;
+  createdAt: string;
+  startedAt: string | null;
+  completedAt: string | null;
+  result: EditableArtifactMaterializationResultResource | null;
+  replayed?: boolean;
+}>;
+
+export type CreateEditableArtifactMaterializationRequest = Readonly<{
+  replicaId: string;
+  idempotencyKey: string;
+  versionId: string;
+  format: EditableArtifactMaterializationFormat;
+  options?: Readonly<Record<string, unknown>>;
+}>;
+
+export type ReadEditableArtifactMaterializationOptions = OpenGeniRequestOptions &
+  Readonly<{ replicaId: string }>;

package/src/editable-artifacts/browser-session.ts

@@ -0,0 +1,176 @@
+import { DOCUMENT_ARTIFACT_COMMAND_VERSION } from "@opengeni/contracts/document-artifact-commands";
+import { PRESENTATION_ARTIFACT_COMMAND_VERSION } from "@opengeni/contracts/presentation-artifact-commands";
+import { SPREADSHEET_ARTIFACT_COMMAND_VERSION } from "@opengeni/contracts/spreadsheet-artifact-commands";
+
+import type { EditableArtifactCacheAuthority } from "./controller";
+import {
+  createEditableArtifactHttpLiveTransport,
+  type CreateEditableArtifactHttpLiveTransportOptions,
+} from "./http-live-transport";
+import { createEditableArtifactSession, type EditableArtifactSession } from "./session";
+import type { EditableArtifactStoragePort } from "./storage";
+import type { EditableArtifactModality } from "./types";
+import {
+  createBrowserEditableArtifactWorkerKernel,
+  type CreateBrowserEditableArtifactWorkerKernelOptions,
+} from "./worker/browser-client";
+
+export type EditableArtifactBrowserRuntime = Omit<
+  CreateBrowserEditableArtifactWorkerKernelOptions,
+  "modality" | "kernelVersion" | "protocolVersion" | "modelSchemaVersion" | "commandVersion"
+> &
+  Readonly<{
+    /** Exact native/WASM build identity admitted by the API. */
+    kernelVersion: string;
+    modelSchemaVersion: number;
+    protocolVersion?: number;
+    commandVersion: number;
+  }>;
+
+export type CreateBrowserEditableArtifactSessionOptions = Readonly<{
+  baseUrl: string | URL;
+  workspaceId: string;
+  artifact: Readonly<{ id: string; modality: EditableArtifactModality }>;
+  /** Exact login/grant partition; rotate authorizationEpoch on authority changes. */
+  storageAuthority: EditableArtifactCacheAuthority;
+  runtime: EditableArtifactBrowserRuntime;
+  transport?: Omit<
+    CreateEditableArtifactHttpLiveTransportOptions,
+    "baseUrl" | "workspaceId" | "protocolVersion" | "kernelVersion" | "modelSchemaVersion"
+  >;
+  storage?: EditableArtifactStoragePort;
+  /** Reuse the replica used to create the artifact when opening it immediately. */
+  replicaId?: string;
+}>;
+
+/**
+ * One production browser composition point: verified WASM Worker, durable WAL,
+ * authenticated HTTP/WebSocket transport, replay, and modality projections.
+ */
+export function createBrowserEditableArtifactSession(
+  options: CreateBrowserEditableArtifactSessionOptions,
+): EditableArtifactSession {
+  const baseUrl = canonicalBaseUrl(options.baseUrl);
+  const workspaceId = boundedIdentity(options.workspaceId, "workspaceId");
+  assertCacheAuthority(options.storageAuthority, baseUrl, workspaceId);
+  const protocolVersion = positiveVersion(options.runtime.protocolVersion ?? 1, "protocolVersion");
+  const modelSchemaVersion = positiveVersion(
+    options.runtime.modelSchemaVersion,
+    "modelSchemaVersion",
+  );
+  const kernelVersion = boundedIdentity(options.runtime.kernelVersion, "kernelVersion", 512);
+  const commandVersion = positiveVersion(options.runtime.commandVersion, "commandVersion");
+  const expectedCommandVersion = commandVersionFor(options.artifact.modality);
+  if (commandVersion !== expectedCommandVersion) {
+    throw new TypeError(
+      `commandVersion ${commandVersion} is incompatible with ${options.artifact.modality} ${expectedCommandVersion}`,
+    );
+  }
+  const {
+    kernelVersion: _kernelVersion,
+    modelSchemaVersion: _modelSchemaVersion,
+    protocolVersion: _protocolVersion,
+    commandVersion: _commandVersion,
+    ...workerOptions
+  } = options.runtime;
+  const worker = createBrowserEditableArtifactWorkerKernel({
+    ...workerOptions,
+    modality: options.artifact.modality,
+    kernelVersion,
+    protocolVersion,
+    modelSchemaVersion,
+    commandVersion,
+  });
+  const replicaId = options.replicaId;
+  try {
+    const transport = createEditableArtifactHttpLiveTransport({
+      ...options.transport,
+      baseUrl,
+      workspaceId,
+      protocolVersion,
+      kernelVersion,
+      modelSchemaVersion,
+    });
+    return createEditableArtifactSession({
+      artifactId: options.artifact.id,
+      modality: options.artifact.modality,
+      storageAuthority: options.storageAuthority,
+      transport,
+      worker,
+      ...(options.storage ? { storage: options.storage } : {}),
+      kernelVersion,
+      modelSchemaVersion,
+      commandVersion,
+      protocolVersion,
+      ...(replicaId ? { writerReplicaIdFactory: () => replicaId } : {}),
+      ownsWorker: true,
+    });
+  } catch (error) {
+    void worker.dispose().catch(() => undefined);
+    throw error;
+  }
+}
+
+/** Generates the portable 64-bit nonzero replica identity used by create/open. */
+export function createEditableArtifactReplicaId(): string {
+  for (;;) {
+    const value = [...crypto.getRandomValues(new Uint8Array(8))]
+      .map((byte) => byte.toString(16).padStart(2, "0"))
+      .join("");
+    if (value !== "0000000000000000") return value;
+  }
+}
+
+function commandVersionFor(modality: EditableArtifactModality): number {
+  switch (modality) {
+    case "spreadsheet":
+      return SPREADSHEET_ARTIFACT_COMMAND_VERSION;
+    case "document":
+      return DOCUMENT_ARTIFACT_COMMAND_VERSION;
+    case "presentation":
+      return PRESENTATION_ARTIFACT_COMMAND_VERSION;
+  }
+}
+
+function canonicalBaseUrl(value: string | URL): URL {
+  const url = new URL(value);
+  if (url.username || url.password || url.search || url.hash) {
+    throw new TypeError("baseUrl must not contain credentials, query, or fragment");
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new TypeError("baseUrl must use HTTP or HTTPS");
+  }
+  return url;
+}
+
+function assertCacheAuthority(
+  authority: EditableArtifactCacheAuthority,
+  baseUrl: URL,
+  workspaceId: string,
+): void {
+  if (new URL(authority.deploymentOrigin).origin !== baseUrl.origin) {
+    throw new TypeError("storageAuthority deployment origin does not match baseUrl");
+  }
+  if (authority.workspaceId !== workspaceId) {
+    throw new TypeError("storageAuthority workspace does not match workspaceId");
+  }
+}
+
+function boundedIdentity(value: string, label: string, maximum = 256): string {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.trim() !== value ||
+    new TextEncoder().encode(value).byteLength > maximum
+  ) {
+    throw new TypeError(`${label} is malformed`);
+  }
+  return value;
+}
+
+function positiveVersion(value: number, label: string): number {
+  if (!Number.isSafeInteger(value) || value < 1 || value > 65_535) {
+    throw new TypeError(`${label} must be a positive 16-bit integer`);
+  }
+  return value;
+}