@opengeni/sdk 0.20.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/sdk",
-  "version": "0.20.0",
+  "version": "0.23.0",
   "description": "Framework-agnostic TypeScript SDK for the OpenGeni API: typed client, session lifecycle, SSE event streaming with reconnect + replay-by-sequence, and proxy re-streaming helpers.",
   "license": "Apache-2.0",
   "repository": {

package/src/client.ts

@@ -16,6 +16,8 @@ import type {
   CodexAccount,
   CodexAccountsResponse,
   CodexRotationSettings,
+  CodexOverviewResponse,
+  CodexAllocatorUpdate,
   CodexConnectionStatus,
   CodexConnectPoll,
   CodexConnectStart,
@@ -28,6 +30,7 @@ import type {
   CapabilityInstallation,
   AddDocumentRequest,
   ClientConfig,
+  WorkspaceModelCatalogResponse,
   ClientSessionEventInput,
   CompactSessionContextResult,
   CompleteFileUploadResponse,
@@ -82,6 +85,9 @@ import type {
   ListWorkspaceMembersResponse,
   PackInstallation,
   ReasoningEffort,
+  RetainedArtifactContent,
+  RetainedArtifactContentOptions,
+  RetainedArtifactMetadata,
   RegisterCapabilityPackRequest,
   ResourceRef,
   ScheduledTask,
@@ -90,12 +96,16 @@ import type {
   SessionListResponse,
   UpdateSessionPinRequest,
   SessionEvent,
+  SessionEventCompactResult,
+  SessionEventCompactResultOptions,
   SessionEventListOptions,
   SessionEventPage,
   SessionGoal,
   SessionHumanInputRequest,
   SessionLineageResponse,
   SessionMcpCredentialUpdateInput,
+  UpdateSessionMcpApprovalPolicyRequest,
+  UpdateSessionMcpApprovalPolicyResponse,
   SessionQueueSnapshot,
   SessionQueueMutationResponse,
   ComposerDraft,
@@ -177,7 +187,11 @@ import type {
   OAuthStartRequest,
   OAuthStartResponse,
 } from "./types";
-import { OPENGENI_API_CONTRACT_HEADER, OPENGENI_API_CONTRACT_REVISION } from "./types";
+import {
+  OPENGENI_API_CONTRACT_HEADER,
+  OPENGENI_API_CONTRACT_REVISION,
+  RETAINED_OUTPUT_MAX_PAGE_BYTES,
+} from "./types";
 
 export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 
@@ -274,6 +288,24 @@ export class OpenGeniClient {
     );
   }
 
+  /**
+   * Replace one attached MCP server's approval policy. The change is captured
+   * by the next claimed attempt; already-claimed work keeps its immutable
+   * policy snapshot.
+   */
+  async updateSessionMcpApprovalPolicy(
+    workspaceId: string,
+    sessionId: string,
+    serverId: string,
+    request: UpdateSessionMcpApprovalPolicyRequest,
+  ): Promise<UpdateSessionMcpApprovalPolicyResponse> {
+    return await this.requestJson<UpdateSessionMcpApprovalPolicyResponse>(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/mcp-servers/${encodeURIComponent(serverId)}/approval-policy`,
+      request,
+    );
+  }
+
   async listSessions(
     workspaceId: string,
     options: {
@@ -533,8 +565,18 @@ export class OpenGeniClient {
   async listEventPage(
     workspaceId: string,
     sessionId: string,
-    options: SessionEventListOptions = {},
-  ): Promise<SessionEventPage> {
+    options: SessionEventCompactResultOptions,
+  ): Promise<SessionEventCompactResult | null>;
+  async listEventPage(
+    workspaceId: string,
+    sessionId: string,
+    options?: SessionEventListOptions,
+  ): Promise<SessionEventPage>;
+  async listEventPage(
+    workspaceId: string,
+    sessionId: string,
+    options: SessionEventListOptions | SessionEventCompactResultOptions = {},
+  ): Promise<SessionEventPage | SessionEventCompactResult | null> {
     if (
       options.latest &&
       ["includeTypes", "excludeTypes", "includeClasses", "excludeClasses"].some((name) =>
@@ -543,22 +585,32 @@ export class OpenGeniClient {
     ) {
       throw new TypeError("latest cannot be combined with event filters");
     }
+    if (options.resultMode === "compact" && !options.latest) {
+      throw new TypeError("resultMode=compact requires latest");
+    }
+    const listOptions: SessionEventListOptions | null =
+      options.resultMode === "compact" ? null : options;
     const response = await this.fetchImpl(
       this.url(`/v1/workspaces/${workspaceId}/sessions/${sessionId}/events`, {
-        ...(options.after !== undefined ? { after: String(options.after) } : {}),
-        ...(options.before !== undefined ? { before: String(options.before) } : {}),
-        ...(options.limit !== undefined ? { limit: String(options.limit) } : {}),
-        ...(options.compact ? { compact: "1" } : {}),
+        ...(listOptions?.after !== undefined ? { after: String(listOptions.after) } : {}),
+        ...(listOptions?.before !== undefined ? { before: String(listOptions.before) } : {}),
+        ...(listOptions?.limit !== undefined ? { limit: String(listOptions.limit) } : {}),
+        ...(listOptions?.compact ? { compact: "1" } : {}),
         ...(options.mode ? { mode: options.mode } : {}),
-        ...(options.direction ? { direction: options.direction } : {}),
+        ...(listOptions?.direction ? { direction: listOptions.direction } : {}),
         ...(options.payloadMode ? { payloadMode: options.payloadMode } : {}),
-        ...(options.includeTypes?.length ? { includeTypes: options.includeTypes.join(",") } : {}),
-        ...(options.excludeTypes?.length ? { excludeTypes: options.excludeTypes.join(",") } : {}),
-        ...(options.includeClasses?.length
-          ? { includeClasses: options.includeClasses.join(",") }
+        ...(options.resultMode ? { resultMode: options.resultMode } : {}),
+        ...(listOptions?.includeTypes?.length
+          ? { includeTypes: listOptions.includeTypes.join(",") }
           : {}),
-        ...(options.excludeClasses?.length
-          ? { excludeClasses: options.excludeClasses.join(",") }
+        ...(listOptions?.excludeTypes?.length
+          ? { excludeTypes: listOptions.excludeTypes.join(",") }
+          : {}),
+        ...(listOptions?.includeClasses?.length
+          ? { includeClasses: listOptions.includeClasses.join(",") }
+          : {}),
+        ...(listOptions?.excludeClasses?.length
+          ? { excludeClasses: listOptions.excludeClasses.join(",") }
           : {}),
         ...(options.latest ? { latest: options.latest } : {}),
       }),
@@ -569,7 +621,11 @@ export class OpenGeniClient {
     );
     assertApiContractResponse(response);
     if (!response.ok) throw new OpenGeniApiError(response.status, await safeText(response));
-    const events = (await response.json()) as SessionEvent[];
+    const body = await response.json();
+    if (options.resultMode === "compact") {
+      return body as SessionEventCompactResult;
+    }
+    const events = body as SessionEvent[];
     const integerHeader = (name: string): number | null => {
       const raw = response.headers.get(name);
       if (raw === null) return null;
@@ -613,6 +669,23 @@ export class OpenGeniClient {
     };
   }
 
+  /**
+   * Fetch the authoritative newest-sequence semantic result directly. This is
+   * the callback-loss recovery path: it reads one compact durable result and
+   * never creates a model turn. `latest: "receipt"` aliases `tool_receipt`;
+   * turn generation remains scoped retry metadata.
+   */
+  async getLatestEventResult(
+    workspaceId: string,
+    sessionId: string,
+    options: Omit<SessionEventCompactResultOptions, "resultMode"> = { latest: "terminal" },
+  ): Promise<SessionEventCompactResult | null> {
+    return await this.listEventPage(workspaceId, sessionId, {
+      ...options,
+      resultMode: "compact",
+    });
+  }
+
   /** POST a user/control event to the session. Returns the accepted event. */
   async sendEvent(
     workspaceId: string,
@@ -1418,6 +1491,14 @@ export class OpenGeniClient {
     return config;
   }
 
+  /** Authenticated model definitions plus workspace-specific selectability. */
+  async getWorkspaceModelCatalog(workspaceId: string): Promise<WorkspaceModelCatalogResponse> {
+    return await this.requestJson<WorkspaceModelCatalogResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/model-catalog`,
+    );
+  }
+
   /** The caller's access context: subject, account + workspace grants, defaults. */
   async getAccessContext(): Promise<AccessContext> {
     return await this.requestJson<AccessContext>("GET", "/v1/access/me");
@@ -1878,6 +1959,80 @@ export class OpenGeniClient {
     );
   }
 
+  /** Read provider-neutral retained evidence metadata; never returns a storage location. */
+  async getRetainedArtifact(
+    workspaceId: string,
+    artifactId: string,
+  ): Promise<RetainedArtifactMetadata> {
+    return await this.requestJson<RetainedArtifactMetadata>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/artifacts/${artifactId}`,
+    );
+  }
+
+  /**
+   * Read at most one authenticated retained-evidence range from the API. This
+   * deliberately does not use the ordinary signed file-download URL.
+   */
+  async getRetainedArtifactContent(
+    workspaceId: string,
+    artifactId: string,
+    options: RetainedArtifactContentOptions = {},
+  ): Promise<RetainedArtifactContent> {
+    if (options.range && (options.range.length > 128 || /[^\x20-\x7e]/.test(options.range))) {
+      throw new RangeError("retained artifact range must be at most 128 printable ASCII bytes");
+    }
+    const response = await this.fetchImpl(
+      this.url(`/v1/workspaces/${workspaceId}/artifacts/${artifactId}/content`),
+      {
+        method: "GET",
+        headers: {
+          ...this.headers(),
+          Accept: "application/octet-stream",
+          ...(options.range ? { Range: options.range } : {}),
+        },
+        ...(options.signal ? { signal: options.signal } : {}),
+      },
+    );
+    try {
+      assertApiContractResponse(response);
+    } catch (error) {
+      await cancelResponseBody(response, "retained artifact API contract mismatch");
+      throw error;
+    }
+    if (!response.ok) {
+      throw new OpenGeniApiError(response.status, await safeBoundedText(response));
+    }
+    if (response.status !== 200 && response.status !== 206) {
+      await cancelResponseBody(response, "unexpected retained artifact response status");
+      throw new OpenGeniApiError(response.status, "unexpected retained artifact response status");
+    }
+    if (response.headers.get("accept-ranges") !== "bytes") {
+      await cancelResponseBody(response, "retained artifact response omitted byte-range support");
+      throw new OpenGeniApiError(502, "retained artifact response omitted byte-range support");
+    }
+    let declaredLength: number | null;
+    try {
+      declaredLength = parseBoundedContentLength(response.headers.get("content-length"));
+    } catch (error) {
+      await cancelResponseBody(response, "invalid retained artifact content-length");
+      throw error;
+    }
+    const bytes = await readBoundedResponseBytes(
+      response,
+      RETAINED_OUTPUT_MAX_PAGE_BYTES,
+      declaredLength,
+    );
+    return {
+      bytes,
+      status: response.status,
+      contentType: response.headers.get("content-type") ?? "application/octet-stream",
+      contentLength: bytes.byteLength,
+      contentRange: response.headers.get("content-range"),
+      acceptRanges: "bytes",
+    };
+  }
+
   /** Mint a short-lived signed download URL for a ready file. */
   async createFileDownloadUrl(
     workspaceId: string,
@@ -2416,6 +2571,14 @@ export class OpenGeniClient {
     );
   }
 
+  /** Live independently-settled quota + reset-credit overview for every account. */
+  async codexOverview(workspaceId: string): Promise<CodexOverviewResponse> {
+    return await this.requestJson<CodexOverviewResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/codex/overview`,
+    );
+  }
+
   /** Disconnect ALL accounts (legacy workspace-wide). Prefer `disconnectCodexAccount`. */
   async codexDisconnect(workspaceId: string): Promise<{ disconnected: boolean }> {
     return await this.requestJson<{ disconnected: boolean }>(
@@ -2458,6 +2621,19 @@ export class OpenGeniClient {
     );
   }
 
+  /** Toggle only NEW automatic allocations under independent allocator OCC. */
+  async setCodexAccountAllocator(
+    workspaceId: string,
+    accountId: string,
+    input: { enabled: boolean; expectedVersion: number },
+  ): Promise<CodexAllocatorUpdate> {
+    return await this.requestJson<CodexAllocatorUpdate>(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/codex/accounts/${accountId}/allocator`,
+      input,
+    );
+  }
+
   /** Disconnect ONE Codex account by id (re-picks active when the removed one was active). */
   async disconnectCodexAccount(
     workspaceId: string,
@@ -2551,3 +2727,69 @@ async function safeText(response: Response): Promise<string> {
     return "";
   }
 }
+
+async function safeBoundedText(response: Response): Promise<string> {
+  try {
+    return new TextDecoder().decode(await readBoundedResponseBytes(response, 64 * 1024, null));
+  } catch {
+    return "";
+  }
+}
+
+async function cancelResponseBody(response: Response, reason: string): Promise<void> {
+  await response.body?.cancel(reason).catch(() => undefined);
+}
+
+function parseBoundedContentLength(value: string | null): number | null {
+  if (value === null) return null;
+  if (!/^\d+$/.test(value)) {
+    throw new OpenGeniApiError(502, "invalid retained artifact content-length");
+  }
+  const length = Number(value);
+  if (!Number.isSafeInteger(length) || length > RETAINED_OUTPUT_MAX_PAGE_BYTES) {
+    throw new OpenGeniApiError(502, "retained artifact response exceeds the SDK byte limit");
+  }
+  return length;
+}
+
+async function readBoundedResponseBytes(
+  response: Response,
+  maxBytes: number,
+  expectedBytes: number | null,
+): Promise<Uint8Array> {
+  if (!response.body) {
+    if (expectedBytes !== null && expectedBytes !== 0) {
+      throw new OpenGeniApiError(502, "retained artifact response length mismatch");
+    }
+    return new Uint8Array();
+  }
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let totalBytes = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      totalBytes += value.byteLength;
+      if (totalBytes > maxBytes) {
+        await reader
+          .cancel("retained artifact response exceeded the SDK byte limit")
+          .catch(() => undefined);
+        throw new OpenGeniApiError(502, "retained artifact response exceeds the SDK byte limit");
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  if (expectedBytes !== null && totalBytes !== expectedBytes) {
+    throw new OpenGeniApiError(502, "retained artifact response length mismatch");
+  }
+  const bytes = new Uint8Array(totalBytes);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}

package/src/index.ts

@@ -85,6 +85,8 @@ export {
   KNOWN_USAGE_EVENT_TYPES,
   OPENGENI_API_CONTRACT_HEADER,
   OPENGENI_API_CONTRACT_REVISION,
+  RETAINED_OUTPUT_DEFAULT_PAGE_BYTES,
+  RETAINED_OUTPUT_MAX_PAGE_BYTES,
   SESSION_EVENT_TYPES,
 } from "./types";
 export type {
@@ -121,12 +123,28 @@ export type {
   CapabilityUnavailableReason,
   ClientConfig,
   ClientModel,
+  ModelAvailabilityV1,
+  ModelBillingAttributionV1,
+  ModelCapabilitiesV1,
+  ModelCapabilityStateV1,
+  ModelCapabilitySupportV1,
+  ModelCredentialReadinessV1,
+  ModelCredentialSourceV1,
+  ModelPricingScheduleV1,
+  ModelPricingV1,
+  WorkspaceModelCatalogModel,
+  WorkspaceModelCatalogResponse,
   CodexAccount,
+  CodexAccountOverview,
   CodexAccountsResponse,
+  CodexAllocatorUpdate,
   CodexAccountSwitchedPayload,
   CodexConnectionStatus,
   CodexConnectStart,
   CodexConnectPoll,
+  CodexOverviewResponse,
+  CodexResetCredit,
+  CodexResetRedemptionRecovery,
   CodexRotationSettings,
   CodexUsage,
   CodexUsageMap,
@@ -212,6 +230,13 @@ export type {
   Permission,
   ProductAccessMode,
   ReasoningEffort,
+  RetainedArtifactContent,
+  RetainedArtifactContentOptions,
+  RetainedArtifactMetadata,
+  RetainedArtifactReference,
+  RetainedArtifactUnavailable,
+  RetainedOutputKind,
+  RetainedOutputUnavailableReason,
   RecordingAvailablePayload,
   RecordingCodec,
   RecordingContentType,
@@ -240,6 +265,7 @@ export type {
   SessionCapabilities,
   SessionListResponse,
   SessionLineageResponse,
+  SessionEffectiveToolPolicy,
   SessionQueueMutationResponse,
   SessionQueueSnapshot,
   SessionControlResponse,
@@ -260,8 +286,10 @@ export type {
   SessionSummary,
   LineageNode,
   SessionMcpCredentialUpdateInput,
+  SessionMcpApprovalPolicy,
   SessionMcpServerInput,
   SessionMcpServerMetadata,
+  SessionToolPolicy,
   // Per-surface capability cell aliases (views of SessionCapabilities).
   FileSystemCapability,
   TerminalCapability,
@@ -283,11 +311,15 @@ export type {
   ViewerHeartbeatRequest,
   ViewerHeartbeatResponse,
   SessionEvent,
+  SessionEventCompactResult,
+  SessionEventCompactResultOptions,
   SessionEventListOptions,
+  SessionEventLatestClass,
   SessionEventPage,
   SessionEventPayloadMode,
   SessionEventReadDirection,
   SessionEventReadMode,
+  SessionEventResultMode,
   SessionEventSemanticClass,
   SessionEventType,
   SessionGoal,
@@ -366,6 +398,8 @@ export type {
   UpdateKnowledgeMemoryRequest,
   UpdateScheduledTaskRequest,
   UpdateSessionGoalRequest,
+  UpdateSessionMcpApprovalPolicyRequest,
+  UpdateSessionMcpApprovalPolicyResponse,
   UpdateSessionPinRequest,
   UpdateSessionRequest,
   UpdateVariableSetRequest,