@opengeni/sdk 3.1.0 → 3.1.2

package/src/artifact-catalog.ts

@@ -0,0 +1,51 @@
+import type { RetainedArtifactReference } from "./types";
+
+export type ArtifactCatalogKind =
+  | "site"
+  | "document"
+  | "spreadsheet"
+  | "presentation"
+  | "image"
+  | "file";
+
+/** Native IDs are unique within a kind; use `${kind}:${id}` as a UI key. */
+export type ArtifactCatalogItem = {
+  id: string;
+  kind: ArtifactCatalogKind;
+  title: string;
+  createdAt: string;
+  updatedAt: string;
+  status: "active" | "archived";
+  /** Shared workspace pin; absent on older servers. Never grants content access. */
+  pinned?: boolean;
+  /** Sites only: "private" when only its owner (the viewer) can see it. */
+  visibility?: "private" | "workspace";
+  /** Present only when the viewer can read this session. */
+  sourceSessionId?: string;
+  versionId?: string;
+  file?: RetainedArtifactReference;
+  filename?: string;
+  contentType?: string;
+  sizeBytes?: number;
+};
+
+export type ArtifactCatalogListOptions = {
+  sourceSessionId?: string;
+  q?: string;
+  kind?: ArtifactCatalogKind;
+  sort?: "updated" | "newest" | "title";
+  status?: "active" | "archived";
+  limit?: number;
+  cursor?: string;
+};
+
+export type ArtifactCatalogListResponse = {
+  items: ArtifactCatalogItem[];
+  nextCursor: string | null;
+};
+
+export type ArtifactPinResponse = {
+  kind: ArtifactCatalogKind;
+  artifactId: string;
+  pinned: boolean;
+};

package/src/artifact-client.ts

@@ -1,4 +1,13 @@
 import { OpenGeniDocumentAuthorityClient } from "./document-authority-client";
+import type { FetchResponse } from "./client";
+import type { SiteToolCallRequest } from "./site-tool-bridge";
+import type { ToolGatewayCallResponse } from "./types";
+import type {
+  CreateWorkspaceArtifactRequest,
+  PublishWorkspaceArtifactVersionRequest,
+  WorkspaceArtifactContentResponse,
+  WorkspaceArtifactMutationResponse,
+} from "./workspace-artifacts";
 import type {
   CreateEditableArtifactMaterializationRequest,
   CreateEditableArtifactResourceRequest,
@@ -12,16 +21,6 @@ import type {
   ReadEditableArtifactMaterializationOptions,
   ReadEditableArtifactResourceOptions,
 } from "./editable-artifact-resources";
-import type {
-  CreateWorkspaceArtifactRequest,
-  PublishWorkspaceArtifactVersionRequest,
-  RollbackWorkspaceArtifactRequest,
-  WorkspaceArtifactContentResponse,
-  WorkspaceArtifactDetailResponse,
-  WorkspaceArtifactListOptions,
-  WorkspaceArtifactListResponse,
-  WorkspaceArtifactMutationResponse,
-} from "./workspace-artifacts";
 
 /** Public SDK client. Optional operator and artifact operations stay out of the console core. */
 export class OpenGeniClient extends OpenGeniDocumentAuthorityClient {
@@ -132,7 +131,7 @@ export class OpenGeniClient extends OpenGeniDocumentAuthorityClient {
     artifactId: string,
     jobId: string,
     options: ReadEditableArtifactMaterializationOptions,
-  ): Promise<Response> {
+  ): Promise<FetchResponse> {
     return await this.requestResponse(
       "GET",
       `/v1/workspaces/${encodeURIComponent(workspaceId)}/editable-artifacts/${encodeURIComponent(artifactId)}/materializations/${encodeURIComponent(jobId)}/download`,
@@ -140,51 +139,52 @@ export class OpenGeniClient extends OpenGeniDocumentAuthorityClient {
       options,
     );
   }
-
-  async listWorkspaceArtifacts(
-    workspaceId: string,
-    options: WorkspaceArtifactListOptions = {},
-  ): Promise<WorkspaceArtifactListResponse> {
-    const query = new URLSearchParams();
-    if (options.limit !== undefined) query.set("limit", String(options.limit));
-    if (options.cursor) query.set("cursor", options.cursor);
-    const suffix = query.size > 0 ? `?${query.toString()}` : "";
-    return await this.requestJson<WorkspaceArtifactListResponse>(
-      "GET",
-      `/v1/workspaces/${workspaceId}/published-artifacts${suffix}`,
-    );
-  }
-
-  async getWorkspaceArtifact(
+  /** Exact Site-version gateway call. Keep this client on the authenticated host;
+   * the API enforces live viewer access and the version's declared tool allowlist. */
+  async callWorkspaceSiteTool(
     workspaceId: string,
-    artifactId: string,
-  ): Promise<WorkspaceArtifactDetailResponse> {
-    return await this.requestJson<WorkspaceArtifactDetailResponse>(
-      "GET",
-      `/v1/workspaces/${workspaceId}/published-artifacts/${encodeURIComponent(artifactId)}`,
+    request: SiteToolCallRequest,
+    options: { signal?: AbortSignal } = {},
+  ): Promise<ToolGatewayCallResponse> {
+    return this.requestJson<ToolGatewayCallResponse>(
+      "POST",
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/tools/calls`,
+      request,
+      undefined,
+      options,
     );
   }
 
   async getWorkspaceArtifactContent(
     workspaceId: string,
     artifactId: string,
-    versionId?: string,
+    versionOrOptions?: string | { versionId?: string; signal?: AbortSignal },
   ): Promise<WorkspaceArtifactContentResponse> {
-    const query = versionId ? `?versionId=${encodeURIComponent(versionId)}` : "";
+    const options =
+      typeof versionOrOptions === "string"
+        ? { versionId: versionOrOptions }
+        : (versionOrOptions ?? {});
+    const query = options.versionId ? `?versionId=${encodeURIComponent(options.versionId)}` : "";
     return await this.requestJson<WorkspaceArtifactContentResponse>(
       "GET",
-      `/v1/workspaces/${workspaceId}/published-artifacts/${encodeURIComponent(artifactId)}/content${query}`,
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/published-artifacts/${encodeURIComponent(artifactId)}/content${query}`,
+      undefined,
+      undefined,
+      options,
     );
   }
 
   async createWorkspaceArtifact(
     workspaceId: string,
     request: CreateWorkspaceArtifactRequest,
+    options: { signal?: AbortSignal } = {},
   ): Promise<WorkspaceArtifactMutationResponse> {
     return await this.requestJson<WorkspaceArtifactMutationResponse>(
       "POST",
-      `/v1/workspaces/${workspaceId}/published-artifacts`,
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/published-artifacts`,
       request,
+      undefined,
+      options,
     );
   }
 
@@ -192,23 +192,14 @@ export class OpenGeniClient extends OpenGeniDocumentAuthorityClient {
     workspaceId: string,
     artifactId: string,
     request: PublishWorkspaceArtifactVersionRequest,
+    options: { signal?: AbortSignal } = {},
   ): Promise<WorkspaceArtifactMutationResponse> {
     return await this.requestJson<WorkspaceArtifactMutationResponse>(
       "POST",
-      `/v1/workspaces/${workspaceId}/published-artifacts/${encodeURIComponent(artifactId)}/versions`,
-      request,
-    );
-  }
-
-  async rollbackWorkspaceArtifact(
-    workspaceId: string,
-    artifactId: string,
-    request: RollbackWorkspaceArtifactRequest,
-  ): Promise<WorkspaceArtifactMutationResponse> {
-    return await this.requestJson<WorkspaceArtifactMutationResponse>(
-      "POST",
-      `/v1/workspaces/${workspaceId}/published-artifacts/${encodeURIComponent(artifactId)}/rollback`,
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/published-artifacts/${encodeURIComponent(artifactId)}/versions`,
       request,
+      undefined,
+      options,
     );
   }
 }

package/src/artifacts.ts

@@ -16,6 +16,7 @@ export type {
 } from "./editable-artifact-resources";
 export type {
   FetchLike,
+  FetchResponse,
   GetSessionOptions,
   OpenGeniClientOptions,
   OpenGeniRequestOptions,

package/src/automations-client.ts

@@ -48,9 +48,12 @@ export class OpenGeniAutomationsClient {
   }
 
   async disableSource(workspaceId: string, sourceId: string): Promise<void> {
-    await this.client.requestJson(
+    await this.client.requestJson<void>(
       "DELETE",
       `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/sources/${encodeURIComponent(sourceId)}`,
+      undefined,
+      {},
+      { responseType: "void" },
     );
   }
 
@@ -90,9 +93,12 @@ export class OpenGeniAutomationsClient {
     triggerId: string,
     expectedRevision: number,
   ): Promise<void> {
-    await this.client.requestJson(
+    await this.client.requestJson<void>(
       "DELETE",
       `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/triggers/${encodeURIComponent(triggerId)}?expectedRevision=${expectedRevision}`,
+      undefined,
+      {},
+      { responseType: "void" },
     );
   }
 

package/src/azure-live-transport.ts

@@ -0,0 +1,286 @@
+import { startCodexRealtimeWebrtc, type StartCodexRealtimeWebrtcOptions } from "./codex-realtime";
+import type { RealtimeControllerTransportStarter } from "./codex-realtime-controller";
+
+type Envelope = Record<string, unknown>;
+const MAX_FRAGMENT_BYTES = 64_000;
+
+/** The most recent speech wins when the user talks for a long time between delegations. */
+function takeUtf8Tail(text: string, maxBytes = MAX_FRAGMENT_BYTES): string {
+  const encoder = new TextEncoder();
+  if (encoder.encode(text).byteLength <= maxBytes) return text;
+  let tail = text.slice(-maxBytes);
+  while (encoder.encode(tail).byteLength > maxBytes) tail = tail.slice(1);
+  return tail;
+}
+
+/** Azure Live has timed transcript fragments, not provider-finalized turns. */
+export class AzureLiveDataChannel extends EventTarget {
+  private pending: {
+    role: "user" | "assistant";
+    text: string;
+    startMs: number;
+    endMs: number;
+  } | null = null;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private ordinal = 0;
+  private readonly prefix = crypto.randomUUID();
+  private closed = false;
+  private closeSent = false;
+  private providerClosed = false;
+  private readonly delegations = new Set<string>();
+  // Azure delegations carry no content, so the user's words since the previous
+  // delegation become the delegation input.
+  private userSinceDelegation = "";
+  private draining: Promise<void> | null = null;
+  private finishDrain: ((error?: Error) => void) | null = null;
+  private readonly onOpen = () => this.dispatchEvent(new Event("open"));
+  private readonly onClose = () => {
+    this.providerClosed = true;
+    this.flush();
+    this.finishDrain?.();
+    this.dispatchEvent(new Event("close"));
+  };
+  private readonly onError = () => this.dispatchEvent(new Event("error"));
+  private readonly onMessage = (event: MessageEvent) => {
+    if (typeof event.data !== "string" || event.data.length > 1_048_576) return;
+    let value: unknown;
+    try {
+      value = JSON.parse(event.data);
+    } catch {
+      return;
+    }
+    if (!value || typeof value !== "object") return;
+    this.receive(value as Envelope);
+  };
+  constructor(
+    private readonly raw: RTCDataChannel,
+    private readonly drainTimeoutMs = 5_000,
+  ) {
+    super();
+    raw.addEventListener("open", this.onOpen);
+    raw.addEventListener("close", this.onClose);
+    raw.addEventListener("error", this.onError);
+    raw.addEventListener("message", this.onMessage);
+  }
+  get readyState(): RTCDataChannelState {
+    return this.closed || this.providerClosed
+      ? "closed"
+      : this.closeSent
+        ? "closing"
+        : this.raw.readyState;
+  }
+  asRtcDataChannel(): RTCDataChannel {
+    return this as unknown as RTCDataChannel;
+  }
+  private emit(value: Envelope): void {
+    if (!this.closed)
+      this.dispatchEvent(new MessageEvent("message", { data: JSON.stringify(value) }));
+  }
+  private flush(): void {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+    const pending = this.pending;
+    this.pending = null;
+    if (!pending?.text) return;
+    this.emit({
+      type: "transcript.segment",
+      turn: {
+        id: `${this.prefix}:${++this.ordinal}`,
+        role: pending.role,
+        transcript: pending.text,
+      },
+      start_ms: pending.startMs,
+      end_ms: pending.endMs,
+    });
+  }
+  private receive(value: Envelope): void {
+    if (this.closed) return;
+    if (
+      value.type === "session.input_transcript.delta" ||
+      value.type === "session.output_transcript.delta"
+    ) {
+      if (
+        typeof value.delta !== "string" ||
+        typeof value.start_ms !== "number" ||
+        typeof value.end_ms !== "number"
+      )
+        return;
+      const role = value.type === "session.input_transcript.delta" ? "user" : "assistant";
+      if (role === "user")
+        this.userSinceDelegation = takeUtf8Tail(this.userSinceDelegation + value.delta);
+      if (
+        this.pending &&
+        (this.pending.role !== role ||
+          new TextEncoder().encode(this.pending.text + value.delta).byteLength > MAX_FRAGMENT_BYTES)
+      )
+        this.flush();
+      if (new TextEncoder().encode(value.delta).byteLength > MAX_FRAGMENT_BYTES) {
+        this.emit({
+          type: "error",
+          error: { message: "Voice transcript fragment exceeded the supported size" },
+        });
+        return;
+      }
+      this.pending = {
+        role,
+        text: (this.pending?.text ?? "") + value.delta,
+        startMs: this.pending?.startMs ?? value.start_ms,
+        endMs: value.end_ms,
+      };
+      // Application grouping only: never present silence as a provider turn boundary.
+      if (!this.timer) this.timer = setTimeout(() => this.flush(), 1_000);
+      return;
+    }
+    if (value.type === "session.delegation.created") {
+      const delegation = value.delegation as Envelope | undefined;
+      if (delegation?.target !== "client" || typeof delegation.id !== "string") return;
+      this.delegations.add(delegation.id);
+      this.flush();
+      const spoken = this.userSinceDelegation.trim();
+      this.userSinceDelegation = "";
+      this.emit({
+        type: "delegation.created",
+        item: {
+          id: delegation.id,
+          type: "delegation",
+          target: "client",
+          content: spoken ? [{ type: "input_text", text: spoken }] : [],
+        },
+        offset_ms: value.offset_ms,
+      });
+      return;
+    }
+    if (value.type === "session.closed") {
+      this.providerClosed = true;
+      this.flush();
+      this.finishDrain?.();
+      return;
+    }
+    if (
+      value.type === "session.started" ||
+      value.type === "session.updated" ||
+      value.type === "error"
+    )
+      this.emit(value);
+  }
+  send(payload: string): void {
+    if (this.readyState !== "open") throw Error("Hosted voice channel is not open");
+    const value = JSON.parse(payload) as Envelope;
+    if (value.type !== "session.context.append" && value.type !== "delegation.context.append")
+      throw Error("Unsupported hosted voice context event");
+    const content = Array.isArray(value.content)
+      ? value.content.map((part) => (typeof part?.text === "string" ? part.text : "")).join("")
+      : "";
+    // Existing bridge chunks are <=500 UTF-8 bytes, below Live's 500-token bound.
+    this.raw.send(
+      JSON.stringify({
+        type:
+          value.channel === "speakable" ? "session.commentary.append" : "session.thinking.append",
+        content,
+        // Replayed tasks from an earlier provider session are general context.
+        delegation_id:
+          value.type === "delegation.context.append" &&
+          typeof value.delegation_item_id === "string" &&
+          this.delegations.has(value.delegation_item_id)
+            ? value.delegation_item_id
+            : null,
+      }),
+    );
+  }
+  drain(): Promise<void> {
+    if (this.draining) return this.draining;
+    if (this.providerClosed || this.raw.readyState === "closed") {
+      this.flush();
+      return Promise.resolve();
+    }
+    if (this.closed || this.raw.readyState !== "open") {
+      return Promise.reject(new Error("Hosted voice close is not confirmed"));
+    }
+    const pending = new Promise<void>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.flush();
+        this.finishDrain?.(
+          new Error("Hosted voice is still closing; retry to preserve final speech"),
+        );
+      }, this.drainTimeoutMs);
+      this.finishDrain = (error) => {
+        clearTimeout(timeout);
+        this.finishDrain = null;
+        if (error) reject(error);
+        else resolve();
+      };
+      if (!this.closeSent) {
+        this.closeSent = true;
+        try {
+          this.raw.send(JSON.stringify({ type: "session.close" }));
+        } catch {
+          this.finishDrain(new Error("Hosted voice close could not be sent"));
+        }
+      }
+    });
+    this.draining = pending;
+    // An uncertain close remains retryable; never resend the provider mutation.
+    void pending.then(
+      () => {
+        if (this.draining === pending) this.draining = null;
+      },
+      () => {
+        if (this.draining === pending) this.draining = null;
+      },
+    );
+    return pending;
+  }
+  close(): void {
+    if (this.closed) return;
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+    this.pending = null;
+    this.finishDrain?.(new Error("Hosted voice channel was disposed before close confirmation"));
+    this.closed = true;
+    this.raw.removeEventListener("open", this.onOpen);
+    this.raw.removeEventListener("close", this.onClose);
+    this.raw.removeEventListener("error", this.onError);
+    this.raw.removeEventListener("message", this.onMessage);
+    this.dispatchEvent(new Event("close"));
+  }
+}
+
+export function createAzureLiveTransportStarter(
+  options: Pick<StartCodexRealtimeWebrtcOptions, "remoteAudio" | "createPeerConnection"> = {},
+): RealtimeControllerTransportStarter {
+  return async (input) => {
+    let channel: AzureLiveDataChannel | undefined;
+    try {
+      const transport = await startCodexRealtimeWebrtc({
+        ...input,
+        ...options,
+        activateRemoteAudio: false,
+        expectedModel: "opengeni-azure/gpt-live-1",
+        onEventsCreated(raw) {
+          channel = new AzureLiveDataChannel(raw);
+          input.onEventsCreated(channel.asRtcDataChannel());
+        },
+        negotiate: (request, requestOptions) =>
+          input.client.negotiateCodexRealtimeWebrtc(
+            input.workspaceId,
+            input.sessionId,
+            request,
+            requestOptions,
+          ),
+      });
+      const events = channel!;
+      return {
+        ...transport,
+        events: events.asRtcDataChannel(),
+        drain: () => events.drain(),
+        stop() {
+          events.close();
+          transport.stop();
+        },
+      };
+    } catch (error) {
+      channel?.close();
+      throw error;
+    }
+  };
+}

package/src/browser.ts

@@ -1,7 +1,28 @@
 /** Browser-console client. Optional SDK surfaces must not enter this eager graph. */
 export { OpenGeniClient as OpenGeniBrowserClient } from "./client";
+export type {
+  SessionMessageSearchRequest,
+  SessionMessageSearchMatch,
+  SessionMessageSearchResponse,
+  SessionMessagePreview,
+  SessionMessagePreviewReference,
+} from "./session-message-search";
+export {
+  OpenGeniToolCallError,
+  OpenGeniToolReapprovalRequiredError,
+  OpenGeniToolsClient,
+} from "./tools";
+export type {
+  OpenGeniGeneratedTools,
+  OpenGeniDynamicToolNode,
+  OpenGeniToolCallOptions,
+  OpenGeniToolFunction,
+  OpenGeniToolsFacade,
+  OpenGeniWorkspaceTools,
+} from "./tools";
 export type {
   FetchLike,
+  FetchResponse,
   GetSessionOptions,
   OpenGeniClientOptions,
   OpenGeniRequestOptions,
@@ -13,9 +34,25 @@ export type {
 export {
   OpenGeniApiContractMismatchError,
   OpenGeniApiError,
+  OpenGeniSetupError,
+  OpenGeniAllowanceExhaustedError,
+  OpenGeniSessionUsageLimitReachedError,
+  OpenGeniSessionUsageLimitUnsupportedError,
+  OpenGeniSecureContextRequiredError,
   OpenGeniSessionListCursorError,
   OpenGeniStreamError,
+  formatErrorMessage,
   isRetryableStreamError,
 } from "./errors";
+export type { OpenGeniSecureContextRequiredReason } from "./errors";
 export { resolveWorkspaceVoiceInputEnabled } from "./transcription";
 export { OPENGENI_API_CONTRACT_HEADER, OPENGENI_API_CONTRACT_REVISION } from "./types";
+
+export type {
+  ConnectorToolPermission,
+  ConnectorToolPermissionEntry,
+  ConnectorToolPermissionsResponse,
+  UpdateConnectorToolPermissionsRequest,
+  SessionMcpToolPermissionsResponse,
+  UpdateSessionMcpToolPermissionsRequest,
+} from "./types";