@opengeni/sdk 0.20.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/sdk",
-  "version": "0.20.0",
+  "version": "0.25.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

@@ -1,4 +1,8 @@
-import { OpenGeniApiContractMismatchError, OpenGeniApiError } from "./errors";
+import {
+  OpenGeniApiContractMismatchError,
+  OpenGeniApiError,
+  OpenGeniSessionListCursorError,
+} from "./errors";
 import {
   streamSessionEvents,
   type SessionEventStreamTransport,
@@ -16,6 +20,8 @@ import type {
   CodexAccount,
   CodexAccountsResponse,
   CodexRotationSettings,
+  CodexOverviewResponse,
+  CodexAllocatorUpdate,
   CodexConnectionStatus,
   CodexConnectPoll,
   CodexConnectStart,
@@ -28,6 +34,7 @@ import type {
   CapabilityInstallation,
   AddDocumentRequest,
   ClientConfig,
+  WorkspaceModelCatalogResponse,
   ClientSessionEventInput,
   CompactSessionContextResult,
   CompleteFileUploadResponse,
@@ -82,6 +89,9 @@ import type {
   ListWorkspaceMembersResponse,
   PackInstallation,
   ReasoningEffort,
+  RetainedArtifactContent,
+  RetainedArtifactContentOptions,
+  RetainedArtifactMetadata,
   RegisterCapabilityPackRequest,
   ResourceRef,
   ScheduledTask,
@@ -90,19 +100,25 @@ import type {
   SessionListResponse,
   UpdateSessionPinRequest,
   SessionEvent,
+  SessionEventCompactResult,
+  SessionEventCompactResultOptions,
   SessionEventListOptions,
   SessionEventPage,
   SessionGoal,
   SessionHumanInputRequest,
   SessionLineageResponse,
   SessionMcpCredentialUpdateInput,
+  UpdateSessionMcpApprovalPolicyRequest,
+  UpdateSessionMcpApprovalPolicyResponse,
   SessionQueueSnapshot,
   SessionQueueMutationResponse,
   ComposerDraft,
   DeleteSessionQueueItemRequest,
   EditSessionQueueItemRequest,
   MoveSessionQueueItemRequest,
+  NewSessionDraft,
   SaveComposerDraftRequest,
+  SaveNewSessionDraftRequest,
   SteerSessionQueueItemRequest,
   SessionControlResponse,
   WorkspaceInferenceControlResponse,
@@ -177,7 +193,22 @@ 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";
+
+function sessionListQuery(options: {
+  limit?: number;
+  parentSessionId?: string | null;
+}): Record<string, string> {
+  const { limit, parentSessionId } = options;
+  return {
+    ...(limit === undefined ? {} : { limit: String(limit) }),
+    ...(parentSessionId === undefined ? {} : { parentSessionId: parentSessionId ?? "null" }),
+  };
+}
 
 export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 
@@ -255,6 +286,24 @@ export class OpenGeniClient {
     );
   }
 
+  async getNewSessionDraft(workspaceId: string): Promise<NewSessionDraft> {
+    return await this.requestJson<NewSessionDraft>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/new-session-draft`,
+    );
+  }
+
+  async saveNewSessionDraft(
+    workspaceId: string,
+    request: SaveNewSessionDraftRequest,
+  ): Promise<NewSessionDraft> {
+    return await this.requestJson<NewSessionDraft>(
+      "PUT",
+      `/v1/workspaces/${workspaceId}/new-session-draft`,
+      request,
+    );
+  }
+
   async getSession(workspaceId: string, sessionId: string): Promise<Session> {
     return await this.requestJson<Session>(
       "GET",
@@ -274,6 +323,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: {
@@ -282,21 +349,21 @@ export class OpenGeniClient {
       search?: string;
     } = {},
   ): Promise<Session[]> {
+    // Search was added with the pin-aware page endpoint. An older API silently
+    // ignores unknown query parameters on the historical array endpoint, which
+    // would turn a search into a plausible-looking unfiltered result. Route
+    // searches through listSessionPage so its rolling-version shape check can
+    // fail explicitly on an older server; retain the array endpoint for every
+    // pre-existing call shape.
+    if (options.search?.trim()) {
+      const page = await this.listSessionPage(workspaceId, options);
+      return [...page.pinned, ...page.sessions];
+    }
     return await this.requestJson<Session[]>(
       "GET",
       `/v1/workspaces/${workspaceId}/sessions`,
       undefined,
-      {
-        ...(options.limit !== undefined ? { limit: String(options.limit) } : {}),
-        ...(options.search?.trim() ? { search: options.search.trim() } : {}),
-        ...(Object.prototype.hasOwnProperty.call(options, "parentSessionId") &&
-        options.parentSessionId !== undefined
-          ? {
-              parentSessionId:
-                options.parentSessionId === null ? "null" : String(options.parentSessionId),
-            }
-          : {}),
-      },
+      sessionListQuery(options),
     );
   }
 
@@ -308,26 +375,51 @@ export class OpenGeniClient {
       parentSessionId?: string | null;
       cursor?: string;
       search?: string;
+      /** Return only the complete personal pinned projection. */
+      pinsOnly?: boolean;
     } = {},
   ): Promise<SessionListResponse> {
-    return await this.requestJson<SessionListResponse>(
-      "GET",
-      `/v1/workspaces/${workspaceId}/sessions`,
-      undefined,
-      {
-        view: "page",
-        ...(options.limit !== undefined ? { limit: String(options.limit) } : {}),
-        ...(options.cursor !== undefined ? { cursor: options.cursor } : {}),
-        ...(options.search?.trim() ? { search: options.search.trim() } : {}),
-        ...(Object.prototype.hasOwnProperty.call(options, "parentSessionId") &&
-        options.parentSessionId !== undefined
-          ? {
-              parentSessionId:
-                options.parentSessionId === null ? "null" : String(options.parentSessionId),
-            }
-          : {}),
-      },
-    );
+    const search = options.search?.trim();
+    let response: SessionListResponse | Session[];
+    try {
+      response = await this.requestJson<SessionListResponse | Session[]>(
+        "GET",
+        `/v1/workspaces/${workspaceId}/sessions`,
+        undefined,
+        {
+          view: "page",
+          ...sessionListQuery(options),
+          ...(options.cursor !== undefined ? { cursor: options.cursor } : {}),
+          ...(search ? { search } : {}),
+          ...(options.pinsOnly ? { pinsOnly: "true" } : {}),
+        },
+      );
+    } catch (error) {
+      if (error instanceof OpenGeniApiError && error.status === 410) {
+        throw new OpenGeniSessionListCursorError(error.status, error.body);
+      }
+      throw error;
+    }
+    if (Array.isArray(response)) {
+      // Rolling/same-major compatibility: an older API ignores `view=page` and
+      // returns the historical array. That is an honest one-page projection;
+      // never pretend it honored a cursor supplied directly by a caller.
+      if (options.cursor) {
+        throw new Error("The connected OpenGeni API does not support stable session-page cursors");
+      }
+      // Older APIs ignore unknown query parameters. Treating their unfiltered
+      // array as a successful search would be worse than an explicit rolling-
+      // upgrade error (and client-side filtering cannot recover matches beyond
+      // the old endpoint's bounded first page).
+      if (search) {
+        throw new Error("The connected OpenGeni API does not support session search");
+      }
+      if (options.pinsOnly) {
+        throw new Error("The connected OpenGeni API does not support pins-only session lists");
+      }
+      return { pinned: [], sessions: response, nextCursor: null };
+    }
+    return response;
   }
 
   /** Set this authenticated member's personal workspace pin for a session. */
@@ -533,8 +625,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 +645,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(",") }
+          : {}),
+        ...(listOptions?.excludeTypes?.length
+          ? { excludeTypes: listOptions.excludeTypes.join(",") }
+          : {}),
+        ...(listOptions?.includeClasses?.length
+          ? { includeClasses: listOptions.includeClasses.join(",") }
           : {}),
-        ...(options.excludeClasses?.length
-          ? { excludeClasses: options.excludeClasses.join(",") }
+        ...(listOptions?.excludeClasses?.length
+          ? { excludeClasses: listOptions.excludeClasses.join(",") }
           : {}),
         ...(options.latest ? { latest: options.latest } : {}),
       }),
@@ -569,7 +681,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 +729,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 +1551,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");
@@ -1838,21 +1979,27 @@ export class OpenGeniClient {
    * -> complete. Returns the ready `FileAsset`.
    */
   async uploadFile(workspaceId: string, input: UploadFileInput): Promise<FileAsset> {
-    // Copy Uint8Array views into a Blob so byte offsets/shared buffers can't
-    // leak surrounding bytes into the PUT body.
+    // Snapshot mutable inputs before hashing so the digest always describes the
+    // exact bytes later sent to object storage. Copy Uint8Array views into a
+    // Blob so byte offsets/shared buffers can't leak surrounding bytes.
     const body: Blob | ArrayBuffer | string =
-      input.data instanceof Uint8Array ? new Blob([input.data.slice()]) : input.data;
+      input.data instanceof Uint8Array
+        ? new Blob([input.data.slice()])
+        : input.data instanceof ArrayBuffer
+          ? input.data.slice(0)
+          : input.data;
     const sizeBytes =
       typeof body === "string"
         ? new TextEncoder().encode(body).byteLength
         : body instanceof Blob
           ? body.size
           : body.byteLength;
+    const sha256 = input.sha256 ?? (await sha256ForUpload(body));
     const upload = await this.beginFileUpload(workspaceId, {
       filename: input.filename,
       contentType: input.contentType,
       sizeBytes,
-      ...(input.sha256 !== undefined ? { sha256: input.sha256 } : {}),
+      sha256,
     });
     const putResponse = await this.fetchImpl(upload.putUrl, {
       method: "PUT",
@@ -1878,6 +2025,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 +2637,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 +2687,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,
@@ -2544,6 +2786,17 @@ function assertApiContractResponse(response: Response): void {
   }
 }
 
+async function sha256ForUpload(body: Blob | ArrayBuffer | string): Promise<string> {
+  const bytes =
+    typeof body === "string"
+      ? new TextEncoder().encode(body)
+      : body instanceof Blob
+        ? new Uint8Array(await body.arrayBuffer())
+        : new Uint8Array(body);
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
 async function safeText(response: Response): Promise<string> {
   try {
     return await response.text();
@@ -2551,3 +2804,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/errors.ts

@@ -1,16 +1,37 @@
 /** Error for a non-2xx OpenGeni API response. */
 export class OpenGeniApiError extends Error {
   readonly status: number;
+  readonly code: string | undefined;
   readonly body: string;
 
   constructor(status: number, body: string) {
-    super(`OpenGeni API ${status}: ${body || "(empty body)"}`);
+    const decoded = decodeApiErrorBody(body);
+    super(`OpenGeni API ${status}: ${decoded.message ?? (body || "(empty body)")}`);
     this.name = "OpenGeniApiError";
     this.status = status;
+    this.code = decoded.code;
     this.body = body;
   }
 }
 
+function decodeApiErrorBody(body: string): { code?: string; message?: string } {
+  if (!body) return {};
+  try {
+    const decoded: unknown = JSON.parse(body);
+    if (!decoded || typeof decoded !== "object" || Array.isArray(decoded)) return {};
+    const record = decoded as Record<string, unknown>;
+    return {
+      ...(typeof record.code === "string" && record.code ? { code: record.code } : {}),
+      ...(typeof record.message === "string" && record.message ? { message: record.message } : {}),
+    };
+  } catch {
+    return {};
+  }
+}
+
+/** A short-lived session-list snapshot cursor can no longer be continued. */
+export class OpenGeniSessionListCursorError extends OpenGeniApiError {}
+
 /** The browser bundle and API disagree about their state-changing wire contract. */
 export class OpenGeniApiContractMismatchError extends Error {
   readonly expected: string;