@opengeni/sdk 0.48.0 → 0.57.0

package/src/memory-slack-client.ts

@@ -0,0 +1,71 @@
+import type { OpenGeniClient as OpenGeniCoreClient } from "./client";
+import type {
+  MemorySlackPublication,
+  MemorySlackPublicationActionRequest,
+  MemorySlackPublicationConfiguration,
+  MemorySlackPublicationConfigurationResponse,
+  MemorySlackPublicationHistoryResponse,
+  SlackPublicationChannelListResponse,
+  UpdateMemorySlackPublicationConfigurationRequest,
+} from "./memory-slack-delivery";
+
+export type OpenGeniMemorySlackTransport = Pick<OpenGeniCoreClient, "requestJson">;
+
+/** Optional Memory-to-Slack API surface, isolated from the eager core client graph. */
+export class OpenGeniMemorySlackClient {
+  constructor(private readonly client: OpenGeniMemorySlackTransport) {}
+
+  async getMemorySlackPublicationConfiguration(
+    workspaceId: string,
+  ): Promise<MemorySlackPublicationConfigurationResponse> {
+    return await this.client.requestJson<MemorySlackPublicationConfigurationResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/memory-slack-publications/configuration`,
+    );
+  }
+
+  async updateMemorySlackPublicationConfiguration(
+    workspaceId: string,
+    request: UpdateMemorySlackPublicationConfigurationRequest,
+  ): Promise<MemorySlackPublicationConfiguration> {
+    return await this.client.requestJson<MemorySlackPublicationConfiguration>(
+      "PUT",
+      `/v1/workspaces/${workspaceId}/memory-slack-publications/configuration`,
+      request,
+    );
+  }
+
+  async listMemorySlackPublicationChannels(
+    workspaceId: string,
+    connectionId: string,
+    cursor?: string,
+  ): Promise<SlackPublicationChannelListResponse> {
+    const query = new URLSearchParams({ connectionId });
+    if (cursor) query.set("cursor", cursor);
+    return await this.client.requestJson<SlackPublicationChannelListResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/memory-slack-publications/channels?${query}`,
+    );
+  }
+
+  async listMemorySlackPublications(
+    workspaceId: string,
+  ): Promise<MemorySlackPublicationHistoryResponse> {
+    return await this.client.requestJson<MemorySlackPublicationHistoryResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/memory-slack-publications`,
+    );
+  }
+
+  async actOnMemorySlackPublication(
+    workspaceId: string,
+    publicationId: string,
+    request: MemorySlackPublicationActionRequest,
+  ): Promise<MemorySlackPublication> {
+    return await this.client.requestJson<MemorySlackPublication>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/memory-slack-publications/${encodeURIComponent(publicationId)}/action`,
+      request,
+    );
+  }
+}

package/src/memory-slack-delivery.ts

@@ -0,0 +1,128 @@
+export type MemorySlackImportance = "major" | "normal" | "minor";
+export type MemorySlackRequestedMode = "auto" | "review" | "never";
+
+export type MemorySlackPublicationDistribution = {
+  importance: MemorySlackImportance;
+  audience: "workspace";
+  slackMode: MemorySlackRequestedMode;
+  shareSummary: string;
+};
+
+export type MemorySlackPublicationConfiguration = {
+  id: string;
+  workspaceId: string;
+  revision: number;
+  enabled: boolean;
+  connectionId: string | null;
+  slackTeamId: string | null;
+  slackChannelId: string | null;
+  slackChannelName: string | null;
+  autoImportances: MemorySlackImportance[];
+  reviewImportances: MemorySlackImportance[];
+  createdBySubjectId: string;
+  createdAt: string;
+};
+
+export type UpdateMemorySlackPublicationConfigurationRequest = {
+  expectedRevision: number;
+  enabled: boolean;
+  connectionId: string | null;
+  slackChannelId: string | null;
+  slackChannelName: string | null;
+  autoImportances: MemorySlackImportance[];
+  reviewImportances: MemorySlackImportance[];
+};
+
+export type MemorySlackPublicationConfigurationResponse = {
+  current: MemorySlackPublicationConfiguration | null;
+  history: MemorySlackPublicationConfiguration[];
+};
+
+export type MemorySlackPublicationState =
+  | "review_pending"
+  | "queued"
+  | "delivering"
+  | "retry_wait"
+  | "delivered"
+  | "rejected"
+  | "failed"
+  | "cancelled";
+
+export type MemorySlackPublicationReceiptKind =
+  | "enqueued"
+  | "review_approved"
+  | "review_rejected"
+  | "delivery_claimed"
+  | "retry_scheduled"
+  | "delivered"
+  | "failed"
+  | "cancelled"
+  | "manual_retry";
+
+export type MemorySlackPublicationReceipt = {
+  id: string;
+  publicationId: string;
+  sequence: number;
+  kind: MemorySlackPublicationReceiptKind;
+  state: MemorySlackPublicationState;
+  attemptNumber: number;
+  actorKind: "human" | "agent" | "service";
+  actorSubjectId: string;
+  operationId: string;
+  errorCode: string | null;
+  retryAt: string | null;
+  slackChannelId: string | null;
+  slackMessageTimestamp: string | null;
+  createdAt: string;
+};
+
+export type MemorySlackPublication = {
+  id: string;
+  workspaceId: string;
+  configurationRevision: number;
+  connectionId: string;
+  slackTeamId: string;
+  slackChannelId: string;
+  sourceType: "workspace_memory" | "durable_learning";
+  sourceId: string;
+  sourceVersion: string | null;
+  importance: MemorySlackImportance;
+  deliveryMode: "auto" | "review";
+  state: MemorySlackPublicationState;
+  summary: string;
+  sourceLabel: string;
+  authoritativePath: string | null;
+  initiatorKind: "human" | "agent" | "service";
+  initiatorSubjectId: string;
+  initiatingHumanSubjectId: string | null;
+  attemptCount: number;
+  retryAt: string | null;
+  lastErrorCode: string | null;
+  slackMessageTimestamp: string | null;
+  deliveredAt: string | null;
+  terminalAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+  receipts: MemorySlackPublicationReceipt[];
+};
+
+export type MemorySlackPublicationHistoryResponse = {
+  publications: MemorySlackPublication[];
+  nextCursor: string | null;
+};
+
+export type MemorySlackPublicationActionRequest = {
+  action: "approve" | "reject" | "retry";
+  expectedState: MemorySlackPublicationState;
+};
+
+export type SlackPublicationChannel = {
+  id: string;
+  name: string | null;
+  isPrivate: boolean;
+};
+
+export type SlackPublicationChannelListResponse = {
+  channels: SlackPublicationChannel[];
+  nextCursor: string | null;
+};

package/src/memory-slack.ts

@@ -0,0 +1,19 @@
+/** Optional Memory-to-Slack API client; import this entry only where the capability is used. */
+export { OpenGeniMemorySlackClient } from "./memory-slack-client";
+export type { OpenGeniMemorySlackTransport } from "./memory-slack-client";
+export type {
+  MemorySlackImportance,
+  MemorySlackPublication,
+  MemorySlackPublicationActionRequest,
+  MemorySlackPublicationConfiguration,
+  MemorySlackPublicationConfigurationResponse,
+  MemorySlackPublicationDistribution,
+  MemorySlackPublicationHistoryResponse,
+  MemorySlackPublicationReceipt,
+  MemorySlackPublicationReceiptKind,
+  MemorySlackPublicationState,
+  MemorySlackRequestedMode,
+  SlackPublicationChannel,
+  SlackPublicationChannelListResponse,
+  UpdateMemorySlackPublicationConfigurationRequest,
+} from "./memory-slack-delivery";

package/src/realtime.ts

@@ -20,7 +20,10 @@ 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. */
@@ -30,7 +33,7 @@ export type SessionRealtimeClientLike = CodexRealtimeControllerClient & {
   ): 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 +56,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 +73,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

@@ -0,0 +1,326 @@
+import type {
+  GeneratedImageReceipt,
+  GeneratedVideoReceipt,
+  MediaGenerationResult,
+  RetainedArtifactReference,
+} 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}$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+const ISO_DATETIME_WITH_OFFSET =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+const WORKSPACE_PATH = /^\/v1\/workspaces\/([0-9a-f-]+)\/artifacts\/([0-9a-f-]+)\/content$/;
+const MAX_BYTES = 64 * 1024 * 1024;
+const MAX_VIDEO_BYTES = 512 * 1024 * 1024;
+const MAX_DIMENSION = 16_384;
+const MAX_PIXELS = 67_108_864;
+const MAX_RANGE_BYTES = 1024 * 1024;
+
+/** Zero-dependency validation for the SDK's permanent generated-image wire receipt. */
+export function parseRetainedGeneratedImageReference(
+  value: unknown,
+  expectedWorkspaceId?: string,
+): RetainedArtifactReference | null {
+  if (!recordWithKeys(value, GENERATED_IMAGE_REFERENCE_KEYS)) return null;
+  const artifact = value as Record<string, unknown>;
+  if (
+    artifact.available !== true ||
+    artifact.kind !== "generated_image" ||
+    typeof artifact.artifactId !== "string" ||
+    !UUID.test(artifact.artifactId) ||
+    !["image/png", "image/jpeg", "image/webp"].includes(String(artifact.contentType)) ||
+    !safeIntegerBetween(artifact.originalBytes, 1, MAX_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.dimensions, DIMENSION_KEYS) ||
+    !recordWithKeys(artifact.retention, RETENTION_KEYS) ||
+    !recordWithKeys(artifact.retrieval, RETRIEVAL_KEYS)
+  ) {
+    return null;
+  }
+  const dimensions = artifact.dimensions as Record<string, unknown>;
+  if (
+    !safeIntegerBetween(dimensions.width, 1, MAX_DIMENSION) ||
+    !safeIntegerBetween(dimensions.height, 1, MAX_DIMENSION) ||
+    Number(dimensions.width) * Number(dimensions.height) > MAX_PIXELS
+  ) {
+    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;
+}
+
+export function generatedImageSandboxPathMatches(
+  artifact: RetainedArtifactReference,
+  sandboxPath: unknown,
+): sandboxPath is string {
+  if (typeof sandboxPath !== "string") return false;
+  const extension =
+    artifact.contentType === "image/png"
+      ? "png"
+      : artifact.contentType === "image/jpeg"
+        ? "jpg"
+        : artifact.contentType === "image/webp"
+          ? "webp"
+          : null;
+  return (
+    extension !== null &&
+    sandboxPath ===
+      `/workspace/generated-images/generated-image-${artifact.artifactId}.${extension}`
+  );
+}
+
+/** Parse the complete closed generated-image tool result. */
+export function parseGeneratedImageReceipt(
+  value: unknown,
+  expectedWorkspaceId?: string,
+): GeneratedImageReceipt | null {
+  if (typeof value === "string" && value.length <= 4_096) {
+    try {
+      return parseGeneratedImageReceipt(JSON.parse(value), expectedWorkspaceId);
+    } catch {
+      return null;
+    }
+  }
+  if (!recordWithKeys(value, GENERATED_IMAGE_RECEIPT_KEYS)) return null;
+  if (value.type !== "generated_image") return null;
+  const artifact = parseRetainedGeneratedImageReference(value.artifact, expectedWorkspaceId);
+  if (!artifact || !generatedImageSandboxPathMatches(artifact, value.sandboxPath)) return null;
+  return { type: "generated_image", artifact, sandboxPath: value.sandboxPath };
+}
+
+/** Zero-dependency validation for a permanent generated-video reference. */
+export function parseRetainedGeneratedVideoReference(
+  value: unknown,
+  expectedWorkspaceId?: string,
+): RetainedArtifactReference | null {
+  if (!recordWithKeys(value, GENERATED_IMAGE_REFERENCE_KEYS)) return null;
+  const artifact = value as Record<string, unknown>;
+  if (
+    artifact.available !== true ||
+    artifact.kind !== "generated_video" ||
+    typeof artifact.artifactId !== "string" ||
+    !UUID.test(artifact.artifactId) ||
+    artifact.contentType !== "video/mp4" ||
+    !safeIntegerBetween(artifact.originalBytes, 1, MAX_VIDEO_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.dimensions, DIMENSION_KEYS) ||
+    !recordWithKeys(artifact.retention, RETENTION_KEYS) ||
+    !recordWithKeys(artifact.retrieval, RETRIEVAL_KEYS)
+  ) {
+    return null;
+  }
+  const dimensions = artifact.dimensions as Record<string, unknown>;
+  if (
+    !safeIntegerBetween(dimensions.width, 1, 8_192) ||
+    !safeIntegerBetween(dimensions.height, 1, 8_192)
+  ) {
+    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 compact successful video result placed in model/timeline history. */
+export function parseGeneratedVideoReceipt(
+  value: unknown,
+  expectedWorkspaceId?: string,
+): GeneratedVideoReceipt | null {
+  if (typeof value === "string" && value.length <= 8_192) {
+    try {
+      return parseGeneratedVideoReceipt(JSON.parse(value), expectedWorkspaceId);
+    } catch {
+      return null;
+    }
+  }
+  if (!recordWithKeys(value, GENERATED_VIDEO_RECEIPT_KEYS)) return null;
+  if (
+    value.type !== "generated_video" ||
+    value.schemaVersion !== 1 ||
+    typeof value.operationId !== "string" ||
+    !UUID.test(value.operationId) ||
+    !recordWithKeys(value.video, GENERATED_VIDEO_FACT_KEYS)
+  ) {
+    return null;
+  }
+  const artifact = parseRetainedGeneratedVideoReference(value.artifact, expectedWorkspaceId);
+  const video = value.video as Record<string, unknown>;
+  if (
+    !artifact ||
+    typeof value.sandboxPath !== "string" ||
+    value.sandboxPath !==
+      `/workspace/generated-videos/generated-video-${artifact.artifactId}.mp4` ||
+    typeof video.durationSeconds !== "number" ||
+    !Number.isFinite(video.durationSeconds) ||
+    video.durationSeconds <= 0 ||
+    video.durationSeconds > 120 ||
+    video.width !== artifact.dimensions?.width ||
+    video.height !== artifact.dimensions?.height ||
+    typeof video.fps !== "number" ||
+    !Number.isFinite(video.fps) ||
+    video.fps <= 0 ||
+    video.fps > 120 ||
+    typeof video.hasAudio !== "boolean" ||
+    video.videoCodec !== "h264" ||
+    (video.audioCodec !== null && video.audioCodec !== "aac")
+  ) {
+    return null;
+  }
+  return value as GeneratedVideoReceipt;
+}
+
+/** Parse one closed terminal envelope; failures never fabricate an artifact. */
+export function parseMediaGenerationResult(
+  value: unknown,
+  expectedWorkspaceId?: string,
+): MediaGenerationResult | null {
+  if (typeof value === "string" && value.length <= 12_000) {
+    try {
+      return parseMediaGenerationResult(JSON.parse(value), expectedWorkspaceId);
+    } catch {
+      return null;
+    }
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const result = value as Record<string, unknown>;
+  if (
+    result.type !== "media_generation_result" ||
+    result.schemaVersion !== 1 ||
+    typeof result.operationId !== "string" ||
+    !UUID.test(result.operationId)
+  ) {
+    return null;
+  }
+  if (result.status === "ready") {
+    if (!recordWithKeys(result, MEDIA_RESULT_READY_KEYS)) return null;
+    const receipt = parseGeneratedVideoReceipt(result.receipt, expectedWorkspaceId);
+    if (!receipt || receipt.operationId !== result.operationId) return null;
+    return value as MediaGenerationResult;
+  }
+  if (
+    !["provider_failed", "retention_failed", "cancelled_before_submit", "outcome_unknown"].includes(
+      String(result.status),
+    ) ||
+    !recordWithKeys(result, MEDIA_RESULT_FAILURE_KEYS) ||
+    typeof result.boundedPublicReason !== "string" ||
+    result.boundedPublicReason.length < 1 ||
+    result.boundedPublicReason.length > 1_000
+  ) {
+    return null;
+  }
+  return value as MediaGenerationResult;
+}
+
+const GENERATED_IMAGE_REFERENCE_KEYS = new Set([
+  "available",
+  "artifactId",
+  "kind",
+  "contentType",
+  "originalBytes",
+  "sha256",
+  "retainedAt",
+  "dimensions",
+  "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 GENERATED_VIDEO_RECEIPT_KEYS = new Set([
+  "type",
+  "schemaVersion",
+  "operationId",
+  "artifact",
+  "video",
+  "sandboxPath",
+]);
+const GENERATED_VIDEO_FACT_KEYS = new Set([
+  "durationSeconds",
+  "width",
+  "height",
+  "fps",
+  "hasAudio",
+  "videoCodec",
+  "audioCodec",
+]);
+const MEDIA_RESULT_READY_KEYS = new Set([
+  "type",
+  "schemaVersion",
+  "status",
+  "operationId",
+  "receipt",
+]);
+const MEDIA_RESULT_FAILURE_KEYS = new Set([
+  "type",
+  "schemaVersion",
+  "status",
+  "operationId",
+  "boundedPublicReason",
+]);
+
+function recordWithKeys(
+  value: unknown,
+  allowed: ReadonlySet<string>,
+): value is Record<string, unknown> {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    Object.keys(value).length === allowed.size &&
+    Object.keys(value).every((key) => allowed.has(key))
+  );
+}
+
+function safeIntegerBetween(value: unknown, min: number, max: number): boolean {
+  return Number.isSafeInteger(value) && Number(value) >= min && Number(value) <= max;
+}