@opengeni/sdk 0.52.1 → 1.0.0

package/src/proxy.ts

@@ -1,5 +1,5 @@
 import type { OpenGeniClient } from "./client";
-import type { StreamSessionEventsOptions } from "./stream";
+import { sessionEventStreamCoveredThrough, type StreamSessionEventsOptions } from "./stream";
 import type { SessionEvent } from "./types";
 
 /**
@@ -12,12 +12,22 @@ import type { SessionEvent } from "./types";
  * OpenGeni's own SSE stream (`id: <sequence>`, `event: <type>`,
  * `data: <event JSON>`), so the browser side can consume it with this same
  * SDK's streaming core (or a plain `EventSource`), including resume via
- * `?after=` / `Last-Event-ID`.
+ * `?after=` / `Last-Event-ID`. An ordinary event uses its own sequence as the
+ * SSE `id`; a compact event uses the server-owned sequence it covers through.
  */
 
-/** Format one event exactly as OpenGeni's API emits it over SSE. */
+/** Format one event with the exact OpenGeni data and resume-cursor semantics. */
 export function formatSseEvent(event: SessionEvent): string {
-  return `id: ${event.sequence}\nevent: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`;
+  const streamedCoverage = sessionEventStreamCoveredThrough(event);
+  const projectedCoverage = event.coveredThrough;
+  const coveredThrough =
+    streamedCoverage ??
+    (typeof projectedCoverage === "number" &&
+    Number.isSafeInteger(projectedCoverage) &&
+    projectedCoverage >= event.sequence
+      ? projectedCoverage
+      : event.sequence);
+  return `id: ${coveredThrough}\nevent: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`;
 }
 
 export type SseReStreamOptions = {
@@ -115,8 +125,9 @@ export function sessionEventsToSseResponse(
 
 /**
  * Read the resume cursor a reconnecting SSE client sent: the `after` query
- * parameter, or the standard `Last-Event-ID` header (the re-emitted stream
- * sets `id:` to the sequence). Returns 0 (full replay) when absent.
+ * parameter, or the standard `Last-Event-ID` header. Re-emitted streams set
+ * `id:` to the event sequence for ordinary events and the covered high-water
+ * sequence for compact events. Returns 0 (full replay) when absent.
  */
 export function resumeSequenceFromRequest(request: Request): number {
   const url = new URL(request.url);

package/src/realtime.ts

@@ -20,17 +20,21 @@ import {
   type CreateCodexRealtimeControllerOptions,
   type RealtimeControllerTransportStarter,
 } from "./codex-realtime-controller";
-import { createGatewayRealtimeTransportStarter } from "./gateway-realtime-transport";
+import {
+  createGatewayRealtimeTransportStarter,
+  createXaiSubscriptionRealtimeTransportStarter,
+} from "./gateway-realtime-transport";
 import type { SessionRealtimeModel, WorkspaceRealtimeModelCatalogResponse } from "./types";
 
 /** Exact backend-facing methods required by the batteries-included realtime SDK. */
 export type SessionRealtimeClientLike = CodexRealtimeControllerClient & {
   getWorkspaceRealtimeModelCatalog(
     workspaceId: string,
+    options?: { signal?: AbortSignal | undefined },
   ): Promise<WorkspaceRealtimeModelCatalogResponse>;
 };
 
-export type SessionRealtimeTransportKind = "codex" | "gateway";
+export type SessionRealtimeTransportKind = "codex" | "gateway" | "xai-subscription";
 
 /** Provider-neutral names for the existing, battle-tested controller projection. */
 export type SessionRealtimeController = CodexRealtimeController;
@@ -53,7 +57,9 @@ export type CreateSessionRealtimeControllerOptions = Omit<
 export function sessionRealtimeTransportKind(
   model: SessionRealtimeModel,
 ): SessionRealtimeTransportKind {
-  return model === "gpt-live-1-boulder-alpha" ? "codex" : "gateway";
+  if (model === "gpt-live-1-boulder-alpha") return "codex";
+  if (model === "supergrok/grok-voice-think-fast-2.0") return "xai-subscription";
+  return "gateway";
 }
 
 /**
@@ -68,13 +74,18 @@ export function createSessionRealtimeController(
   return createCodexRealtimeController({
     ...options,
     ownerStorageNamespace: sessionRealtimeOwnerStorageNamespace(options.model),
-    ...(transport === "gateway" ? { startTransport: createGatewayRealtimeTransportStarter() } : {}),
+    ...(transport === "gateway"
+      ? { startTransport: createGatewayRealtimeTransportStarter() }
+      : transport === "xai-subscription"
+        ? { startTransport: createXaiSubscriptionRealtimeTransportStarter() }
+        : {}),
   });
 }
 
 export {
   createCodexRealtimeController,
   createGatewayRealtimeTransportStarter,
+  createXaiSubscriptionRealtimeTransportStarter,
   hasStoredSessionRealtimeOwnerProof,
   sessionRealtimeOwnerStorageKey,
   sessionRealtimeOwnerStorageNamespace,

package/src/retained-artifacts.ts

@@ -3,6 +3,7 @@ import type {
   GeneratedVideoReceipt,
   MediaGenerationResult,
   RetainedArtifactReference,
+  SandboxFileArtifactReceipt,
 } from "./types";
 
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
@@ -15,6 +16,94 @@ const MAX_VIDEO_BYTES = 512 * 1024 * 1024;
 const MAX_DIMENSION = 16_384;
 const MAX_PIXELS = 67_108_864;
 const MAX_RANGE_BYTES = 1024 * 1024;
+const MAX_SANDBOX_FILE_BYTES = 25 * 1024 * 1024 - 1;
+
+/** Zero-dependency validation for a permanent generic workspace-file receipt. */
+export function parseRetainedWorkspaceFileReference(
+  value: unknown,
+  expectedWorkspaceId?: string,
+): RetainedArtifactReference | null {
+  if (!recordWithKeys(value, WORKSPACE_FILE_REFERENCE_KEYS)) return null;
+  const artifact = value as Record<string, unknown>;
+  if (
+    artifact.available !== true ||
+    artifact.kind !== "file" ||
+    typeof artifact.artifactId !== "string" ||
+    !UUID.test(artifact.artifactId) ||
+    typeof artifact.contentType !== "string" ||
+    !/^[a-z0-9][a-z0-9!#$&^_.+-]{0,62}\/[a-z0-9][a-z0-9!#$&^_.+-]{0,62}$/.test(
+      artifact.contentType,
+    ) ||
+    !safeIntegerBetween(artifact.originalBytes, 1, MAX_SANDBOX_FILE_BYTES) ||
+    typeof artifact.sha256 !== "string" ||
+    !SHA256.test(artifact.sha256) ||
+    typeof artifact.retainedAt !== "string" ||
+    artifact.retainedAt.length > 64 ||
+    !ISO_DATETIME_WITH_OFFSET.test(artifact.retainedAt) ||
+    !Number.isFinite(Date.parse(artifact.retainedAt)) ||
+    !recordWithKeys(artifact.retention, RETENTION_KEYS) ||
+    !recordWithKeys(artifact.retrieval, RETRIEVAL_KEYS)
+  ) {
+    return null;
+  }
+  const retention = artifact.retention as Record<string, unknown>;
+  if (retention.policy !== "workspace_file" || retention.expiresAt !== null) return null;
+  const retrieval = artifact.retrieval as Record<string, unknown>;
+  if (
+    retrieval.method !== "GET" ||
+    retrieval.acceptRanges !== "bytes" ||
+    retrieval.maxRangeBytes !== MAX_RANGE_BYTES ||
+    typeof retrieval.path !== "string" ||
+    retrieval.path.length > 256
+  ) {
+    return null;
+  }
+  const match = WORKSPACE_PATH.exec(retrieval.path);
+  if (
+    !match ||
+    !UUID.test(match[1] ?? "") ||
+    match[2] !== artifact.artifactId ||
+    (expectedWorkspaceId !== undefined && match[1] !== expectedWorkspaceId)
+  ) {
+    return null;
+  }
+  return value as RetainedArtifactReference;
+}
+
+/** Parse the closed result returned by sandbox_file_publish and the session API. */
+export function parseSandboxFileArtifactReceipt(
+  value: unknown,
+  expectedWorkspaceId?: string,
+): SandboxFileArtifactReceipt | null {
+  if (typeof value === "string" && value.length <= 8_192) {
+    try {
+      return parseSandboxFileArtifactReceipt(JSON.parse(value), expectedWorkspaceId);
+    } catch {
+      return null;
+    }
+  }
+  if (!recordWithKeys(value, SANDBOX_FILE_RECEIPT_KEYS)) return null;
+  const artifact = parseRetainedWorkspaceFileReference(value.artifact, expectedWorkspaceId);
+  const pathSegments = typeof value.sandboxPath === "string" ? value.sandboxPath.split("/") : [];
+  if (
+    value.type !== "sandbox_file" ||
+    typeof value.sandboxPath !== "string" ||
+    !value.sandboxPath.startsWith("/workspace/") ||
+    value.sandboxPath.length > 4_096 ||
+    value.sandboxPath.includes("\0") ||
+    pathSegments.some(
+      (segment, index) => index > 1 && (!segment || segment === "." || segment === ".."),
+    ) ||
+    typeof value.filename !== "string" ||
+    value.filename.length < 1 ||
+    value.filename.length > 1_024 ||
+    pathSegments.at(-1) !== value.filename ||
+    !artifact
+  ) {
+    return null;
+  }
+  return value as SandboxFileArtifactReceipt;
+}
 
 /** Zero-dependency validation for the SDK's permanent generated-image wire receipt. */
 export function parseRetainedGeneratedImageReference(
@@ -272,10 +361,22 @@ const GENERATED_IMAGE_REFERENCE_KEYS = new Set([
   "retention",
   "retrieval",
 ]);
+const WORKSPACE_FILE_REFERENCE_KEYS = new Set([
+  "available",
+  "artifactId",
+  "kind",
+  "contentType",
+  "originalBytes",
+  "sha256",
+  "retainedAt",
+  "retention",
+  "retrieval",
+]);
 const DIMENSION_KEYS = new Set(["width", "height"]);
 const RETENTION_KEYS = new Set(["policy", "expiresAt"]);
 const RETRIEVAL_KEYS = new Set(["method", "path", "acceptRanges", "maxRangeBytes"]);
 const GENERATED_IMAGE_RECEIPT_KEYS = new Set(["type", "artifact", "sandboxPath"]);
+const SANDBOX_FILE_RECEIPT_KEYS = new Set(["type", "sandboxPath", "filename", "artifact"]);
 const GENERATED_VIDEO_RECEIPT_KEYS = new Set([
   "type",
   "schemaVersion",

package/src/session-history-import.ts

@@ -0,0 +1,84 @@
+import type { OpenGeniClient } from "./client";
+import type {
+  AppendArchivedSessionEventsRequest,
+  AppendArchivedSessionEventsResponse,
+  ImportArchivedSessionRequest,
+  ImportArchivedSessionResponse,
+} from "@opengeni/contracts";
+
+export type {
+  ArchivedSessionImportEvent,
+  AppendArchivedSessionEventsRequest,
+  AppendArchivedSessionEventsResponse,
+  ImportArchivedSessionRequest,
+  ImportArchivedSessionResponse,
+  SessionImportedArchive,
+} from "@opengeni/contracts";
+
+type SessionHistoryImportClient = Pick<OpenGeniClient, "requestJson">;
+
+/**
+ * Server-only migration of a read-only archive, not model-facing conversation
+ * history. Use an asUser client to preserve the verified creator/owner. Persist
+ * importId and retry the exact request after an uncertain outcome.
+ * Requires sessions:create in the authenticated actor's permissions.
+ */
+export function importArchivedSession(
+  client: SessionHistoryImportClient,
+  workspaceId: string,
+  request: ImportArchivedSessionRequest,
+): Promise<ImportArchivedSessionResponse> {
+  return client.requestJson(
+    "POST",
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/session-imports`,
+    request,
+  );
+}
+
+/**
+ * Append historical events at the acknowledged nextOffset. Retrying the exact
+ * batchId, offset and events replays its receipt; conflicting reuse returns 409.
+ * Each request accepts at most 100 events / 1 MiB, with 256 KiB per event.
+ * Requires sessions:control and the same authenticated importer.
+ */
+export function appendArchivedSessionEvents(
+  client: SessionHistoryImportClient,
+  workspaceId: string,
+  importId: string,
+  request: AppendArchivedSessionEventsRequest,
+): Promise<AppendArchivedSessionEventsResponse> {
+  return client.requestJson(
+    "POST",
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/session-imports/${encodeURIComponent(importId)}/events`,
+    request,
+  );
+}
+
+/** Import through an existing external tenant mapping; this does not onboard it. */
+export function importExternalWorkspaceArchivedSession(
+  client: SessionHistoryImportClient,
+  source: string,
+  externalId: string,
+  request: ImportArchivedSessionRequest,
+): Promise<ImportArchivedSessionResponse> {
+  return client.requestJson(
+    "POST",
+    `/v1/workspaces/external/${encodeURIComponent(source)}/${encodeURIComponent(externalId)}/session-imports`,
+    request,
+  );
+}
+
+/** Append to an archive through the same external tenant mapping and actor. */
+export function appendExternalWorkspaceArchivedSessionEvents(
+  client: SessionHistoryImportClient,
+  source: string,
+  externalId: string,
+  importId: string,
+  request: AppendArchivedSessionEventsRequest,
+): Promise<AppendArchivedSessionEventsResponse> {
+  return client.requestJson(
+    "POST",
+    `/v1/workspaces/external/${encodeURIComponent(source)}/${encodeURIComponent(externalId)}/session-imports/${encodeURIComponent(importId)}/events`,
+    request,
+  );
+}

package/src/session-list-entries.ts

@@ -0,0 +1 @@
+export { sessionListEntry } from "@opengeni/contracts/session-list-entries";

package/src/session-message-search.ts

@@ -0,0 +1,47 @@
+/** Literal Unicode case-insensitive substring. Whitespace is significant. */
+export type SessionMessageSearchRequest = {
+  query: string;
+  sessionId?: string | undefined;
+  /** Workspace-only first hit per session; cannot combine with sessionId. */
+  groupBy?: "session" | undefined;
+  archiveStatus?: "active" | "archived" | "all" | undefined;
+  limit?: number | undefined;
+  cursor?: string | undefined;
+};
+
+export type SessionMessageSearchMatch = {
+  sessionId: string;
+  sessionTitle: string | null;
+  eventId: string;
+  sequence: number;
+  turnId: string | null;
+  role: "user" | "assistant";
+  messageId: string | null;
+  /** Zero-based UTF-16 offset in the complete visible message. */
+  messageMatchOffset: number;
+  /** Zero-based UTF-16 offsets in text; matchEnd is exclusive. */
+  snippet: { text: string; matchStart: number; matchEnd: number };
+};
+
+export type SessionMessageSearchResponse = {
+  matches: SessionMessageSearchMatch[];
+  nextCursor: string | null;
+  /** Empty advancing pages are valid. Continue until false. */
+  hasMore: boolean;
+  /** Cumulative distinct messages visited in this live traversal. */
+  scannedMessages: number;
+  /** Cumulative matching messages, or session representatives with groupBy=session. */
+  matchedMessageCount: number;
+  /** Cumulative occurrences, or session representatives with groupBy=session. */
+  matchedOccurrenceCount: number;
+  /** True only on exhaustion. Concurrent mutations require a fresh traversal. */
+  countIsExact: boolean;
+};
+
+/** Exact selected event reference from a search match; no payload fields are read. */
+export type SessionMessagePreviewReference = { eventId: string; sequence: number };
+
+/** A complete visible message, or an explicit over-12,000-UTF-16-unit result. */
+export type SessionMessagePreview =
+  | { status: "available"; text: string }
+  | { status: "unavailable" };

package/src/session-proxy-client.ts

@@ -0,0 +1,64 @@
+import type { OpenGeniEmbeddingClient } from "./embedding-client";
+import type { OpenGeniRequestOptions, FetchResponse } from "./client";
+import type { AccessGrant } from "./types";
+
+/** Maximum actual UTF-8 bytes forwarded for one embedded Site HTML response. */
+export const SESSION_PROXY_SITE_HTML_MAX_BYTES = 25 * 1024 * 1024;
+
+/** A streaming Site download exceeded the host proxy's actual-byte ceiling. */
+export class SessionProxySiteHtmlTooLargeError extends Error {
+  readonly code = "site_html_too_large";
+  readonly limitBytes = SESSION_PROXY_SITE_HTML_MAX_BYTES;
+
+  constructor() {
+    super(`Site HTML exceeds the ${SESSION_PROXY_SITE_HTML_MAX_BYTES}-byte proxy limit.`);
+    this.name = "SessionProxySiteHtmlTooLargeError";
+  }
+}
+
+/** Server-only effective grant read; never derive external authority from access/me snapshots. */
+export function getSessionProxyWorkspaceGrant(
+  client: Pick<OpenGeniEmbeddingClient, "requestJson">,
+  workspaceId: string,
+  options: OpenGeniRequestOptions = {},
+): Promise<AccessGrant> {
+  return client.requestJson(
+    "GET",
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/access/grant`,
+    undefined,
+    {},
+    options,
+  );
+}
+
+/** Exact association read. The API reauthorizes the source session on every call. */
+export function getSessionProxyArtifactAssociation(
+  client: Pick<OpenGeniEmbeddingClient, "requestJson">,
+  workspaceId: string,
+  sessionId: string,
+  kind: "editable" | "site",
+  artifactId: string,
+  options: OpenGeniRequestOptions = {},
+): Promise<{ sessionId: string; artifactId: string; kind: "editable" | "site" }> {
+  return client.requestJson(
+    "GET",
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/sessions/${encodeURIComponent(sessionId)}/artifact-associations/${encodeURIComponent(artifactId)}`,
+    undefined,
+    { kind },
+    options,
+  );
+}
+
+/** Authenticated response stream for the server proxy; does not buffer Site HTML. */
+export function downloadSessionProxySiteHtml(
+  client: Pick<OpenGeniEmbeddingClient, "requestJsonResponse">,
+  workspaceId: string,
+  artifactId: string,
+  options: { versionId: string; signal?: AbortSignal },
+): Promise<FetchResponse> {
+  return client.requestJsonResponse(
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/published-artifacts/${encodeURIComponent(artifactId)}/html`,
+    { versionId: options.versionId },
+    options,
+  );
+}