@opengeni/sdk 3.1.0 → 3.1.2

package/src/organization-integration-policy.ts

@@ -0,0 +1,54 @@
+import type { OpenGeniClient } from "./client";
+
+export type OrganizationIntegrationPolicy = {
+  mode: "unrestricted" | "restricted";
+  allowedIntegrationKeys: string[];
+  revision: number;
+};
+
+export type UpdateOrganizationIntegrationPolicyRequest = {
+  mode: "unrestricted" | "restricted";
+  allowedIntegrationKeys: string[];
+  expectedRevision: number;
+  operationId: string;
+};
+
+type PolicyClient = Pick<OpenGeniClient, "requestJson">;
+
+export type OrganizationIntegrationCatalog = {
+  integrations: Array<{ key: string; label: string; kind: "curated" | "custom" }>;
+};
+
+/** Discover stable policy identities; integrations must not guess provider identifiers. */
+export async function getOrganizationIntegrationCatalog(
+  client: PolicyClient,
+  organizationId: string,
+): Promise<OrganizationIntegrationCatalog> {
+  return client.requestJson(
+    "GET",
+    `/v1/organizations/${encodeURIComponent(organizationId)}/integration-policy/catalog`,
+  );
+}
+
+export async function getOrganizationIntegrationPolicy(
+  client: PolicyClient,
+  organizationId: string,
+): Promise<OrganizationIntegrationPolicy> {
+  return client.requestJson(
+    "GET",
+    `/v1/organizations/${encodeURIComponent(organizationId)}/integration-policy`,
+  );
+}
+
+/** Retain operationId and the exact request when reconciling an uncertain outcome. */
+export async function updateOrganizationIntegrationPolicy(
+  client: PolicyClient,
+  organizationId: string,
+  request: UpdateOrganizationIntegrationPolicyRequest,
+): Promise<OrganizationIntegrationPolicy> {
+  return client.requestJson(
+    "PUT",
+    `/v1/organizations/${encodeURIComponent(organizationId)}/integration-policy`,
+    request,
+  );
+}

package/src/pr-review-client.ts

@@ -12,7 +12,7 @@ import type {
 
 export type OpenGeniPrReviewTransport = Pick<OpenGeniCoreClient, "requestJson" | "requestVoid">;
 
-/** Optional OpenGeni Review Bot API surface, isolated from the eager core client graph. */
+/** Optional Opengeni Review Bot API surface, isolated from the eager core client graph. */
 export class OpenGeniPrReviewClient {
   constructor(private readonly client: OpenGeniPrReviewTransport) {}
 

package/src/pr-review.ts

@@ -1,4 +1,4 @@
-/** Optional OpenGeni Review Bot API client; import this entry only where the capability is used. */
+/** Optional Opengeni Review Bot API client; import this entry only where the capability is used. */
 export { OpenGeniPrReviewClient } from "./pr-review-client";
 export type { OpenGeniPrReviewTransport } from "./pr-review-client";
 export type {

package/src/preference-registry.ts

@@ -10,6 +10,8 @@ export type PreferenceRegistryProvenanceSource =
   | "human"
   | "onboarding"
   | "knowledge_proposal"
+  | "agent"
+  | "portable_skill"
   | "imported_document"
   | "slack"
   | "meeting_transcript"

package/src/prepared-mcp-setup.ts

@@ -0,0 +1,123 @@
+import type {
+  CustomMcpSetupRequest,
+  PreparedMcpSetup,
+} from "@opengeni/contracts/prepared-mcp-setup";
+
+const record = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+const keys = (value: Record<string, unknown>, allowed: string[]) =>
+  Object.keys(value).every((key) => allowed.includes(key));
+const text = (value: unknown, max: number, min = 1): value is string =>
+  typeof value === "string" && value.length >= min && value.length <= max;
+const trimmedText = (value: unknown, max: number): value is string =>
+  typeof value === "string" && text(value.trim(), max);
+const headerPart = (value: unknown): value is string =>
+  text(value, 16_384, 0) && !/[\r\n\0]/.test(value);
+const fieldId = (value: unknown): value is string =>
+  typeof value === "string" && /^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(value);
+const endpoint = (value: unknown): value is string => {
+  if (!text(value, 2048)) return false;
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" && !url.username && !url.password && !url.search && !url.hash;
+  } catch {
+    return false;
+  }
+};
+
+/** Browser/native-safe display projection. The API owns authoritative schema
+ * validation; parity tests keep this lightweight parser aligned without pulling
+ * schema runtimes into the SDK or replaying unknown fields into a secret form. */
+export function parseCustomMcpSetupRequest(value: unknown): CustomMcpSetupRequest | null {
+  if (
+    !record(value) ||
+    !keys(value, ["kind", "name", "endpointUrl", "rationale", "ownership", "mcpSetup"]) ||
+    value.kind !== "mcp" ||
+    !trimmedText(value.name, 256) ||
+    !endpoint(value.endpointUrl) ||
+    !trimmedText(value.rationale, 2000)
+  )
+    return null;
+  const base = {
+    kind: "mcp" as const,
+    name: value.name.trim(),
+    endpointUrl: value.endpointUrl,
+    rationale: value.rationale.trim(),
+  };
+  if (value.ownership === undefined && value.mcpSetup === undefined) return base;
+  if (value.ownership !== "personal" && value.ownership !== "workspace") return null;
+  const setup = value.mcpSetup;
+  if (
+    !record(setup) ||
+    !keys(setup, ["name", "endpointUrl", "headers", "secretFields"]) ||
+    !trimmedText(setup.name, 256) ||
+    setup.name.trim() !== base.name ||
+    setup.endpointUrl !== base.endpointUrl ||
+    !Array.isArray(setup.headers) ||
+    setup.headers.length < 1 ||
+    setup.headers.length > 32 ||
+    !Array.isArray(setup.secretFields) ||
+    setup.secretFields.length > 32
+  )
+    return null;
+  const fields: PreparedMcpSetup["secretFields"] = [];
+  const fieldIds = new Set<string>();
+  for (const field of setup.secretFields) {
+    if (
+      !record(field) ||
+      !keys(field, ["id", "label"]) ||
+      !fieldId(field.id) ||
+      !trimmedText(field.label, 256) ||
+      fieldIds.has(field.id)
+    )
+      return null;
+    fieldIds.add(field.id);
+    fields.push({ id: field.id, label: field.label.trim() });
+  }
+  const headers: PreparedMcpSetup["headers"] = [];
+  const names = new Set<string>();
+  const used = new Set<string>();
+  for (const header of setup.headers) {
+    if (
+      !record(header) ||
+      !text(header.name, 256) ||
+      !/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(header.name)
+    )
+      return null;
+    const name = header.name.toLowerCase();
+    if (names.has(name)) return null;
+    names.add(name);
+    if ("value" in header) {
+      if (
+        !keys(header, ["name", "value"]) ||
+        !headerPart(header.value) ||
+        !header.value ||
+        ["authorization", "proxy-authorization", "cookie", "x-api-key", "api-key"].includes(name)
+      )
+        return null;
+      headers.push({ name: header.name, value: header.value });
+    } else {
+      if (
+        !keys(header, ["name", "secret", "prefix", "suffix"]) ||
+        !fieldId(header.secret) ||
+        !fieldIds.has(header.secret) ||
+        (header.prefix !== undefined && !headerPart(header.prefix)) ||
+        (header.suffix !== undefined && !headerPart(header.suffix))
+      )
+        return null;
+      used.add(header.secret);
+      headers.push({
+        name: header.name,
+        secret: header.secret,
+        ...(header.prefix !== undefined ? { prefix: header.prefix as string } : {}),
+        ...(header.suffix !== undefined ? { suffix: header.suffix as string } : {}),
+      });
+    }
+  }
+  if (used.size !== fieldIds.size) return null;
+  return {
+    ...base,
+    ownership: value.ownership,
+    mcpSetup: { name: base.name, endpointUrl: base.endpointUrl, headers, secretFields: fields },
+  };
+}

package/src/proxy.ts

@@ -1,23 +1,33 @@
 import type { OpenGeniClient } from "./client";
-import type { StreamSessionEventsOptions } from "./stream";
+import { sessionEventStreamCoveredThrough, type StreamSessionEventsOptions } from "./stream";
 import type { SessionEvent } from "./types";
 
 /**
  * Proxy-through-your-own-API helpers.
  *
- * The intended pattern: a customer's server consumes the OpenGeni event
+ * The intended pattern: a customer's server consumes the Opengeni event
  * stream with its own API key (`client.streamEvents(...)`) and re-emits it to
- * its browser clients over its own authenticated endpoint — the OpenGeni key
+ * its browser clients over its own authenticated endpoint — the Opengeni key
  * never reaches the browser. The re-emitted wire format is identical to
- * OpenGeni's own SSE stream (`id: <sequence>`, `event: <type>`,
+ * 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 = {
@@ -28,7 +38,7 @@ export type SseReStreamOptions = {
   heartbeatMs?: number;
   /**
    * Called when the downstream consumer cancels (e.g. the browser
-   * disconnected). Use it to abort the upstream OpenGeni stream — an async
+   * disconnected). Use it to abort the upstream Opengeni stream — an async
    * iterator that is mid-`await` cannot be interrupted by `return()` alone.
    */
   onCancel?: () => void;
@@ -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);
@@ -136,12 +147,12 @@ export type ProxySessionEventStreamOptions = Omit<StreamSessionEventsOptions, "a
 };
 
 /**
- * One-call proxy: consume the OpenGeni stream server-side and return an SSE
+ * One-call proxy: consume the Opengeni stream server-side and return an SSE
  * `Response` for your own browser clients. Works anywhere WHATWG `Response`
  * is the handler return type (Hono, Next.js route handlers, Bun.serve,
  * Cloudflare Workers, ...).
  *
- * The upstream OpenGeni connection is torn down when the downstream client
+ * The upstream Opengeni connection is torn down when the downstream client
  * disconnects, and also when `options.signal` (e.g. the incoming request's
  * signal) aborts.
  */

package/src/realtime.ts

@@ -1,3 +1,4 @@
+import { createAzureLiveTransportStarter } from "./azure-live-transport";
 /**
  * Public, provider-neutral realtime browser SDK.
  *
@@ -30,10 +31,11 @@ import type { SessionRealtimeModel, WorkspaceRealtimeModelCatalogResponse } from
 export type SessionRealtimeClientLike = CodexRealtimeControllerClient & {
   getWorkspaceRealtimeModelCatalog(
     workspaceId: string,
+    options?: { signal?: AbortSignal | undefined },
   ): Promise<WorkspaceRealtimeModelCatalogResponse>;
 };
 
-export type SessionRealtimeTransportKind = "codex" | "gateway" | "xai-subscription";
+export type SessionRealtimeTransportKind = "codex" | "gateway" | "xai-subscription" | "azure-live";
 
 /** Provider-neutral names for the existing, battle-tested controller projection. */
 export type SessionRealtimeController = CodexRealtimeController;
@@ -56,6 +58,7 @@ export type CreateSessionRealtimeControllerOptions = Omit<
 export function sessionRealtimeTransportKind(
   model: SessionRealtimeModel,
 ): SessionRealtimeTransportKind {
+  if (model === "opengeni-azure/gpt-live-1") return "azure-live";
   if (model === "gpt-live-1-boulder-alpha") return "codex";
   if (model === "supergrok/grok-voice-think-fast-2.0") return "xai-subscription";
   return "gateway";
@@ -73,11 +76,18 @@ export function createSessionRealtimeController(
   return createCodexRealtimeController({
     ...options,
     ownerStorageNamespace: sessionRealtimeOwnerStorageNamespace(options.model),
-    ...(transport === "gateway"
-      ? { startTransport: createGatewayRealtimeTransportStarter() }
-      : transport === "xai-subscription"
-        ? { startTransport: createXaiSubscriptionRealtimeTransportStarter() }
-        : {}),
+    ...(transport === "azure-live"
+      ? {
+          startTransport: createAzureLiveTransportStarter({
+            remoteAudio: options.remoteAudio,
+            createPeerConnection: options.createPeerConnection,
+          }),
+        }
+      : transport === "gateway"
+        ? { startTransport: createGatewayRealtimeTransportStarter() }
+        : transport === "xai-subscription"
+          ? { startTransport: createXaiSubscriptionRealtimeTransportStarter() }
+          : {}),
   });
 }
 

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,68 @@
+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. `retained` proves a generated image or video, or a published sandbox
+ * file, originated in that session.
+ */
+export function getSessionProxyArtifactAssociation(
+  client: Pick<OpenGeniEmbeddingClient, "requestJson">,
+  workspaceId: string,
+  sessionId: string,
+  kind: "editable" | "site" | "retained",
+  artifactId: string,
+  options: OpenGeniRequestOptions = {},
+): Promise<{ sessionId: string; artifactId: string; kind: "editable" | "site" | "retained" }> {
+  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,
+  );
+}