@opengeni/sdk 0.46.0 → 0.48.0

package/README.md

@@ -408,7 +408,7 @@ Every public endpoint group has typed methods:
 | Turn queue | `getQueue`, `moveQueueItem`, `editQueueItem`, `steerQueueItem`, `deleteQueueItem` |
 | Goal | `getGoal`, `updateGoal`, `pauseGoal`, `resumeGoal` |
 | Scheduled tasks | `createScheduledTask`, `listScheduledTasks`, `getScheduledTask`, `updateScheduledTask`, `pauseScheduledTask`, `resumeScheduledTask`, `triggerScheduledTask`, `deleteScheduledTask`, `listScheduledTaskRuns` |
-| Variable sets | `listVariable sets`, `createVariable set`, `getVariable set`, `updateVariable set`, `deleteVariable set`, `setVariable setVariable`, `deleteVariable setVariable` (values are write-only) |
+| Variable sets | `listVariableSets`, `createVariableSet`, `getVariableSet`, `updateVariableSet`, `deleteVariableSet`, `setVariableSetVariable`, `deleteVariableSetVariable`; generic reads are metadata-only, while dedicated permissioned exact-value reads are part of the held client train |
 | Files | `uploadFile`, `beginFileUpload`, `completeFileUpload`, `getFile`, `createFileDownloadUrl` |
 | Documents | `createDocumentBase`, `listDocumentBases`, `getDocumentBase`, `addDocument`, `listDocuments`, `reindexDocument`, `searchDocuments`, `searchKnowledge` (effective organization + workspace + immutable initiating-user personal scope) |
 | Packs | `listPacks`, `registerPack`, `getPack`, `enablePack`, `deletePack`, `listPackInstallations` |

package/dist/{chunk-QKV5OCLJ.js → chunk-MBGBLVUV.js}

@@ -82,6 +82,9 @@ async function* streamSessionEvents(transport, options = {}) {
   const reconnect = options.reconnect ?? true;
   const baseDelayMs = options.reconnectDelayMs ?? 500;
   const maxDelayMs = options.maxReconnectDelayMs ?? 1e4;
+  const jitterRatio = options.reconnectJitterRatio ?? 0.2;
+  const beforeLiveTimeoutMs = options.beforeLiveTimeoutMs ?? 15e3;
+  const heartbeatTimeoutMs = options.heartbeatTimeoutMs ?? 45e3;
   const maxAttempts = options.maxReconnectAttempts ?? Number.POSITIVE_INFINITY;
   let cursor = options.after ?? 0;
   let failedAttempts = 0;
@@ -96,9 +99,15 @@ async function* streamSessionEvents(transport, options = {}) {
       everConnected = true;
       failedAttempts = 0;
       delayMs = baseDelayMs;
-      await options.beforeLive?.();
+      try {
+        options.onOpen?.();
+      } catch {
+      }
+      await runBeforeLive(options.beforeLive, beforeLiveTimeoutMs, signal);
       options.onStateChange?.("live");
-      for await (const message of parseSseStream(body)) {
+      for await (const message of parseSseStream(
+        withStreamInactivityTimeout(body, heartbeatTimeoutMs, signal)
+      )) {
         if (signal?.aborted) {
           return;
         }
@@ -122,7 +131,7 @@ async function* streamSessionEvents(transport, options = {}) {
         return;
       }
       if (cursor === cursorAtOpen) {
-        await sleep(baseDelayMs, signal);
+        await sleep(jitteredDelay(baseDelayMs, jitterRatio), signal);
       }
       continue;
     } catch (error) {
@@ -139,10 +148,76 @@ async function* streamSessionEvents(transport, options = {}) {
         );
       }
     }
-    await sleep(delayMs, signal);
+    await sleep(jitteredDelay(delayMs, jitterRatio), signal);
     delayMs = Math.min(Math.max(delayMs * 2, baseDelayMs), maxDelayMs);
   }
 }
+async function runBeforeLive(beforeLive, timeoutMs, signal) {
+  if (!beforeLive) return;
+  let timer;
+  let abortListener;
+  const timeout = new Promise((_resolve, reject) => {
+    timer = setTimeout(
+      () => reject(new TypeError(`stream reconciliation timed out after ${timeoutMs}ms`)),
+      timeoutMs
+    );
+    if (signal) {
+      abortListener = () => reject(new DOMException("Aborted", "AbortError"));
+      signal.addEventListener("abort", abortListener, { once: true });
+    }
+  });
+  try {
+    await Promise.race([Promise.resolve().then(beforeLive), timeout]);
+  } finally {
+    if (timer !== void 0) clearTimeout(timer);
+    if (signal && abortListener) signal.removeEventListener("abort", abortListener);
+  }
+}
+function jitteredDelay(delayMs, ratio) {
+  if (delayMs <= 0 || ratio <= 0) return delayMs;
+  const boundedRatio = Math.min(ratio, 1);
+  const spread = delayMs * boundedRatio;
+  return Math.max(0, delayMs - spread + Math.random() * spread * 2);
+}
+function withStreamInactivityTimeout(stream, timeoutMs, signal) {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+    throw new RangeError("stream heartbeat timeout must be a positive safe integer");
+  }
+  const reader = stream.getReader();
+  return new ReadableStream({
+    pull: async (controller) => {
+      let timer;
+      let abortListener;
+      try {
+        const result = await Promise.race([
+          reader.read(),
+          new Promise((_resolve, reject) => {
+            timer = setTimeout(
+              () => reject(new TypeError(`event stream heartbeat timed out after ${timeoutMs}ms`)),
+              timeoutMs
+            );
+            if (signal) {
+              abortListener = () => reject(new DOMException("Aborted", "AbortError"));
+              signal.addEventListener("abort", abortListener, { once: true });
+            }
+          })
+        ]);
+        if (result.done) controller.close();
+        else controller.enqueue(result.value);
+      } catch (error) {
+        void reader.cancel(error).catch(() => {
+        });
+        controller.error(error);
+      } finally {
+        if (timer !== void 0) clearTimeout(timer);
+        if (signal && abortListener) signal.removeEventListener("abort", abortListener);
+      }
+    },
+    cancel: async (reason) => {
+      await reader.cancel(reason);
+    }
+  });
+}
 async function* backfillEvents(transport, fromExclusive, toInclusive) {
   let cursor = fromExclusive;
   while (cursor < toInclusive) {
@@ -197,6 +272,9 @@ async function* streamWorkspaceControlEvents(transport, options = {}) {
   const reconnect = options.reconnect ?? true;
   const baseDelayMs = options.reconnectDelayMs ?? 500;
   const maxDelayMs = options.maxReconnectDelayMs ?? 1e4;
+  const jitterRatio = options.reconnectJitterRatio ?? 0.2;
+  const beforeLiveTimeoutMs = options.beforeLiveTimeoutMs ?? 15e3;
+  const heartbeatTimeoutMs = options.heartbeatTimeoutMs ?? 45e3;
   const maxAttempts = options.maxReconnectAttempts ?? Number.POSITIVE_INFINITY;
   let cursor = options.after ?? 0;
   let failures = 0;
@@ -211,9 +289,11 @@ async function* streamWorkspaceControlEvents(transport, options = {}) {
       everConnected = true;
       failures = 0;
       delayMs = baseDelayMs;
-      await options.beforeLive?.();
+      await runBeforeLive(options.beforeLive, beforeLiveTimeoutMs, signal);
       options.onStateChange?.("live");
-      for await (const message of parseSseStream(body)) {
+      for await (const message of parseSseStream(
+        withStreamInactivityTimeout(body, heartbeatTimeoutMs, signal)
+      )) {
         if (signal?.aborted) return;
         const event = parseWorkspaceControlEvent(message.data);
         if (!event || event.sequence <= cursor) continue;
@@ -221,7 +301,7 @@ async function* streamWorkspaceControlEvents(transport, options = {}) {
         yield event;
       }
       if (!reconnect) return;
-      if (cursor === cursorAtOpen) await sleep2(baseDelayMs, signal);
+      if (cursor === cursorAtOpen) await sleep2(jitteredDelay(baseDelayMs, jitterRatio), signal);
       continue;
     } catch (error) {
       if (signal?.aborted || isAbortError(error)) return;
@@ -233,7 +313,7 @@ async function* streamWorkspaceControlEvents(transport, options = {}) {
         );
       }
     }
-    await sleep2(delayMs, signal);
+    await sleep2(jitteredDelay(delayMs, jitterRatio), signal);
     delayMs = Math.min(Math.max(delayMs * 2, baseDelayMs), maxDelayMs);
   }
 }
@@ -421,8 +501,14 @@ var KNOWN_PERMISSIONS = [
   "connections:write",
   "environments:manage",
   "environments:use",
+  "variable-sets:list",
+  "variable-sets:read",
+  "variable-sets:write",
   "variable-sets:manage",
   "variable-sets:use",
+  "secrets:list",
+  "secrets:read",
+  "secrets:write",
   "mcp_servers:attach",
   "toolspace:call",
   "goals:manage",
@@ -438,6 +524,7 @@ var OPENGENI_API_CONTRACT_HEADER = "x-opengeni-api-contract";
 var OPENGENI_CORRELATION_HEADER = "x-opengeni-correlation-id";
 var RETAINED_OUTPUT_DEFAULT_PAGE_BYTES = 256 * 1024;
 var RETAINED_OUTPUT_MAX_PAGE_BYTES = 1024 * 1024;
+var COMPUTER_SCREENSHOT_MAX_BYTES = 32 * 1024 * 1024;
 var KNOWN_USAGE_EVENT_TYPES = [
   "agent_run.created",
   "agent_run.completed",
@@ -465,6 +552,8 @@ var OpenGeniClient = class {
   baseUrl;
   options;
   fetchImpl;
+  readInFlight = /* @__PURE__ */ new Map();
+  readTrailing = /* @__PURE__ */ new Map();
   constructor(options) {
     this.baseUrl = options.baseUrl.replace(/\/+$/, "");
     this.options = options;
@@ -476,7 +565,11 @@ var OpenGeniClient = class {
     const correlationId = crypto.randomUUID();
     const form = new FormData();
     const filename = filenameForAudioMimeType(input.mimeType);
-    const audio = input.audio instanceof File ? input.audio : input.audio instanceof Uint8Array ? new File([Uint8Array.from(input.audio)], filename, { type: input.mimeType }) : new File([input.audio], filename, { type: input.mimeType || input.audio.type });
+    const audio = input.audio instanceof File ? input.audio : input.audio instanceof Uint8Array ? new File([Uint8Array.from(input.audio)], filename, {
+      type: input.mimeType
+    }) : new File([input.audio], filename, {
+      type: input.mimeType || input.audio.type
+    });
     form.append("audio", audio, filename);
     form.append("mimeType", input.mimeType);
     if (input.durationSeconds !== void 0) {
@@ -486,7 +579,10 @@ var OpenGeniClient = class {
     try {
       response = await this.fetchImpl(this.url(`/v1/workspaces/${workspaceId}/transcriptions`), {
         method: "POST",
-        headers: { ...this.headers(correlationId), Accept: "application/json" },
+        headers: {
+          ...this.headers(correlationId),
+          Accept: "application/json"
+        },
         body: form,
         ...input.signal ? { signal: input.signal } : {}
       });
@@ -495,7 +591,11 @@ var OpenGeniClient = class {
       throw mutationTransportError(correlationId);
     }
     assertApiContractResponse(response);
-    if (!response.ok) throw await apiErrorFromResponse(response, { method: "POST", correlationId });
+    if (!response.ok)
+      throw await apiErrorFromResponse(response, {
+        method: "POST",
+        correlationId
+      });
     await assertJsonResponse(response, { method: "POST", correlationId });
     let body;
     try {
@@ -580,7 +680,11 @@ var OpenGeniClient = class {
       throw mutationTransportError(correlationId);
     }
     assertApiContractResponse(response);
-    if (!response.ok) throw await apiErrorFromResponse(response, { method: "PUT", correlationId });
+    if (!response.ok)
+      throw await apiErrorFromResponse(response, {
+        method: "PUT",
+        correlationId
+      });
     await assertJsonResponse(response, { method: "PUT", correlationId });
     const body = await response.json().catch(() => null);
     if (!isUploadTranscriptionRecordingChunkResponse(body)) {
@@ -649,11 +753,9 @@ var OpenGeniClient = class {
       request
     );
   }
-  async getSession(workspaceId, sessionId) {
-    return await this.requestJson(
-      "GET",
-      `/v1/workspaces/${workspaceId}/sessions/${sessionId}`
-    );
+  async getSession(workspaceId, sessionId, options = {}) {
+    const path = `/v1/workspaces/${workspaceId}/sessions/${sessionId}`;
+    return await this.singleFlightRead(path, () => this.requestJson("GET", path), options);
   }
   async updateSession(workspaceId, sessionId, request) {
     return await this.requestJson(
@@ -746,10 +848,34 @@ var OpenGeniClient = class {
     );
   }
   async getSessionLineage(workspaceId, sessionId) {
-    return await this.requestJson(
-      "GET",
-      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/lineage`
-    );
+    const path = `/v1/workspaces/${workspaceId}/sessions/${sessionId}/lineage`;
+    return await this.singleFlightRead(
+      path,
+      () => this.requestJson("GET", path)
+    );
+  }
+  singleFlightRead(key, read, options = {}) {
+    const existing = this.readInFlight.get(key);
+    if (existing) {
+      if (!options.fresh) return existing;
+      const queued = this.readTrailing.get(key);
+      if (queued) return queued;
+      const trailing = existing.then(
+        () => this.singleFlightRead(key, read),
+        () => this.singleFlightRead(key, read)
+      );
+      this.readTrailing.set(key, trailing);
+      const clear = () => {
+        if (this.readTrailing.get(key) === trailing) this.readTrailing.delete(key);
+      };
+      void trailing.then(clear, clear);
+      return trailing;
+    }
+    const promise = read().finally(() => {
+      if (this.readInFlight.get(key) === promise) this.readInFlight.delete(key);
+    });
+    this.readInFlight.set(key, promise);
+    return promise;
   }
   /** Negotiate one server-mediated connected-Codex GPT-Live V3 WebRTC call. */
   async negotiateCodexRealtimeWebrtc(workspaceId, sessionId, request, options = {}) {
@@ -826,7 +952,9 @@ var OpenGeniClient = class {
   }
   /** Newest turn that durably emitted `turn.started`, or null before any admission. */
   async getLatestStartedTurn(workspaceId, sessionId) {
-    const turns = await this.listTurns(workspaceId, sessionId, { latestStarted: true });
+    const turns = await this.listTurns(workspaceId, sessionId, {
+      latestStarted: true
+    });
     return turns[0] ?? null;
   }
   // --- Bring-your-own-compute: Machines dashboard + metrics (M10) ------------
@@ -860,6 +988,19 @@ var OpenGeniClient = class {
     );
     return response.samples;
   }
+  /**
+   * Remove one connected self-hosted machine enrollment. The control-plane
+   * operation works while the agent is offline, revokes future reconnects,
+   * retains history, and returns a typed blocker when active route/lease or
+   * recovery dependencies make removal unsafe. `idempotencyKey` is replay-safe.
+   */
+  async removeEnrollment(workspaceId, enrollmentId, request = {}) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/enrollments/${enrollmentId}/revoke`,
+      request
+    );
+  }
   // --- Self-hosted enrollment UX (design 11) --------------------------------
   /**
    * Resolve a pending device-enrollment flow by its user_code for the click-Grant
@@ -1144,9 +1285,10 @@ var OpenGeniClient = class {
   }
   // --- Turn queue ------------------------------------------------------------
   async getQueue(workspaceId, sessionId) {
-    return await this.requestJson(
-      "GET",
-      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/queue`
+    const path = `/v1/workspaces/${workspaceId}/sessions/${sessionId}/queue`;
+    return await this.singleFlightRead(
+      path,
+      () => this.requestJson("GET", path)
     );
   }
   async moveQueueItem(workspaceId, sessionId, turnId, request) {
@@ -1314,10 +1456,8 @@ var OpenGeniClient = class {
   // --- Goals -------------------------------------------------------------------
   /** The session's goal. 404s when the session never had one. */
   async getGoal(workspaceId, sessionId) {
-    return await this.requestJson(
-      "GET",
-      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/goal`
-    );
+    const path = `/v1/workspaces/${workspaceId}/sessions/${sessionId}/goal`;
+    return await this.singleFlightRead(path, () => this.requestJson("GET", path));
   }
   async updateGoal(workspaceId, sessionId, request) {
     return await this.requestJson(
@@ -1377,6 +1517,16 @@ var OpenGeniClient = class {
       options
     );
   }
+  /** FileSystem: hydrate several independent directories behind one sandbox lease. */
+  async fsListBatch(workspaceId, sessionId, request, options = {}) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/list-batch`,
+      request,
+      {},
+      options
+    );
+  }
   /** FileSystem: read a file (text or base64; binary-safe, size-capped). */
   async fsRead(workspaceId, sessionId, request, options = {}) {
     return await this.requestJson(
@@ -1439,6 +1589,16 @@ var OpenGeniClient = class {
       options
     );
   }
+  /** Git: read status and optional diffs for several repositories behind one sandbox lease. */
+  async gitReadBatch(workspaceId, sessionId, request, options = {}) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/git/read-batch`,
+      request,
+      {},
+      options
+    );
+  }
   /** Git: commit log. */
   async gitLog(workspaceId, sessionId, request = {}) {
     return await this.requestJson(
@@ -1911,7 +2071,8 @@ var OpenGeniClient = class {
     );
   }
   // --- VariableSets --------------------------------------------------------------
-  // Variable values are write-only: reads return name/version metadata only.
+  // Generic reads return name/version metadata only. Plaintext uses one
+  // dedicated permissioned endpoint.
   async listVariableSets(workspaceId) {
     return await this.requestJson(
       "GET",
@@ -1931,6 +2092,12 @@ var OpenGeniClient = class {
       `/v1/workspaces/${workspaceId}/variable-sets/${variableSetId}`
     );
   }
+  async getVariableSetVariable(workspaceId, variableSetId, name) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/variable-sets/${variableSetId}/variables/${encodeURIComponent(name)}`
+    );
+  }
   async updateVariableSet(workspaceId, variableSetId, request) {
     return await this.requestJson(
       "PATCH",
@@ -1944,7 +2111,7 @@ var OpenGeniClient = class {
       `/v1/workspaces/${workspaceId}/variable-sets/${variableSetId}`
     );
   }
-  /** Create or rotate a variable. The value never comes back on any read. */
+  /** Create or rotate a variable. Generic reads never return its value. */
   async setVariableSetVariable(workspaceId, variableSetId, name, value) {
     return await this.requestJson(
       "PUT",
@@ -2076,18 +2243,23 @@ var OpenGeniClient = class {
   }
   // --- Files -----------------------------------------------------------------------
   /** Step 1 of the upload flow: returns the pre-signed PUT target. */
-  async beginFileUpload(workspaceId, request) {
+  async beginFileUpload(workspaceId, request, options = {}) {
     return await this.requestJson(
       "POST",
       `/v1/workspaces/${workspaceId}/files/uploads`,
-      request
+      request,
+      {},
+      options
     );
   }
   /** Step 3 of the upload flow: server verifies the object and marks it ready. */
-  async completeFileUpload(workspaceId, uploadId) {
+  async completeFileUpload(workspaceId, uploadId, options = {}) {
     const response = await this.requestJson(
       "POST",
-      `/v1/workspaces/${workspaceId}/files/uploads/${uploadId}/complete`
+      `/v1/workspaces/${workspaceId}/files/uploads/${uploadId}/complete`,
+      void 0,
+      {},
+      options
     );
     return response.file;
   }
@@ -2097,35 +2269,68 @@ var OpenGeniClient = class {
    * -> complete. Returns the ready `FileAsset`.
    */
   async uploadFile(workspaceId, input) {
+    if (input.timeoutMs !== void 0 && (!Number.isFinite(input.timeoutMs) || input.timeoutMs <= 0)) {
+      throw new Error("File upload timeout must be a positive number");
+    }
+    const withTimeout = async (timeoutMs, operation) => {
+      const controller = new AbortController();
+      let timeout;
+      const timedOut = new Promise((_resolve, reject) => {
+        timeout = setTimeout(() => {
+          controller.abort();
+          reject(new Error("File upload timed out. Retry the upload."));
+        }, timeoutMs);
+      });
+      try {
+        return await Promise.race([operation(controller.signal), timedOut]);
+      } finally {
+        if (timeout !== void 0) clearTimeout(timeout);
+      }
+    };
     const body = 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,
-      sha256
-    });
-    const putResponse = await this.fetchImpl(upload.putUrl, {
-      method: "PUT",
-      // Signed object-storage URLs carry their own short-lived authority.
-      // Browser cookies and HTTP auth must never accompany this cross-origin
-      // request: credentialed fetches are incompatible with wildcard CORS and
-      // can leak ambient credentials to a caller-selected storage endpoint.
-      credentials: "omit",
-      // The backend's requiredHeaders already carry the canonical lowercase
-      // `content-type` for every storage backend (Azure/S3/GCS). Do NOT also set
-      // a `Content-Type` key here: WHATWG Headers treats the two casings as the
-      // same header and comma-joins their values (e.g. "text/plain, text/plain"),
-      // which the object store persists verbatim and COMPLETE then rejects (422),
-      // and which breaks S3's presigned-URL signature.
-      headers: { ...upload.requiredHeaders },
-      body
-    });
+    const upload = await withTimeout(
+      3e4,
+      async (signal) => await this.beginFileUpload(
+        workspaceId,
+        {
+          filename: input.filename,
+          contentType: input.contentType,
+          sizeBytes,
+          sha256
+        },
+        { signal }
+      )
+    );
+    const transferTimeoutMs = input.timeoutMs ?? Math.max(12e4, Math.ceil(sizeBytes / (256 * 1024)) * 1e3);
+    const putResponse = await withTimeout(
+      transferTimeoutMs,
+      async (signal) => await this.fetchImpl(upload.putUrl, {
+        method: "PUT",
+        // Signed object-storage URLs carry their own short-lived authority.
+        // Browser cookies and HTTP auth must never accompany this cross-origin
+        // request: credentialed fetches are incompatible with wildcard CORS and
+        // can leak ambient credentials to a caller-selected storage endpoint.
+        credentials: "omit",
+        // The backend's requiredHeaders already carry the canonical lowercase
+        // `content-type` for every storage backend (Azure/S3/GCS). Do NOT also set
+        // a `Content-Type` key here: WHATWG Headers treats the two casings as the
+        // same header and comma-joins their values (e.g. "text/plain, text/plain"),
+        // which the object store persists verbatim and COMPLETE then rejects (422),
+        // and which breaks S3's presigned-URL signature.
+        headers: { ...upload.requiredHeaders },
+        body,
+        signal
+      })
+    );
     if (!putResponse.ok) {
       throw await apiErrorFromResponse(putResponse, { method: "PUT" });
     }
-    return await this.completeFileUpload(workspaceId, upload.uploadId);
+    return await withTimeout(
+      3e4,
+      async (signal) => await this.completeFileUpload(workspaceId, upload.uploadId, { signal })
+    );
   }
   async getFile(workspaceId, fileId) {
     return await this.requestJson(
@@ -2145,22 +2350,83 @@ var OpenGeniClient = class {
    * deliberately does not use the ordinary signed file-download URL.
    */
   async getRetainedArtifactContent(workspaceId, artifactId, options = {}) {
+    return await this.getRetainedArtifactContentAtPath(
+      `/v1/workspaces/${workspaceId}/artifacts/${artifactId}/content`,
+      options
+    );
+  }
+  async getSessionRetainedArtifact(workspaceId, sessionId, artifactId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/artifacts/${artifactId}`
+    );
+  }
+  async getSessionRetainedArtifactContent(workspaceId, sessionId, artifactId, options = {}) {
+    return await this.getRetainedArtifactContentAtPath(
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/artifacts/${artifactId}/content`,
+      options
+    );
+  }
+  /** Assemble one retained screenshot from bounded authenticated API ranges. */
+  async downloadRetainedScreenshot(workspaceId, sessionId, artifactId, options = {}) {
+    const maxRetries = options.maxRetries ?? 2;
+    if (!Number.isInteger(maxRetries) || maxRetries < 0 || maxRetries > 3) {
+      throw new RangeError("retained screenshot maxRetries must be an integer from 0 to 3");
+    }
+    const metadata = await this.getSessionRetainedArtifact(workspaceId, sessionId, artifactId);
+    if (!metadata.available) return { metadata, bytes: null };
+    if (metadata.kind !== "computer_screenshot" || metadata.contentType !== "image/png" || !metadata.dimensions || metadata.originalBytes <= 0 || metadata.originalBytes > COMPUTER_SCREENSHOT_MAX_BYTES) {
+      throw new OpenGeniApiError(502, "retained screenshot metadata is invalid");
+    }
+    const bytes = new Uint8Array(metadata.originalBytes);
+    const pageBytes = Math.min(metadata.retrieval.maxRangeBytes, RETAINED_OUTPUT_MAX_PAGE_BYTES);
+    if (!Number.isSafeInteger(pageBytes) || pageBytes <= 0) {
+      throw new OpenGeniApiError(502, "retained screenshot range metadata is invalid");
+    }
+    for (let start = 0; start < bytes.byteLength; start += pageBytes) {
+      options.signal?.throwIfAborted();
+      const end = Math.min(start + pageBytes, bytes.byteLength) - 1;
+      let page = null;
+      for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+        try {
+          page = await this.getSessionRetainedArtifactContent(workspaceId, sessionId, artifactId, {
+            range: `bytes=${start}-${end}`,
+            ...options.signal ? { signal: options.signal } : {}
+          });
+          break;
+        } catch (error) {
+          options.signal?.throwIfAborted();
+          if (attempt >= maxRetries || error instanceof OpenGeniApiError && error.status >= 400 && error.status < 500) {
+            throw error;
+          }
+        }
+      }
+      if (!page) throw new OpenGeniApiError(502, "retained screenshot range retry exhausted");
+      const expectedLength = end - start + 1;
+      if (page.status !== 206 || page.contentType !== metadata.contentType || page.contentLength !== expectedLength || page.contentRange !== `bytes ${start}-${end}/${metadata.originalBytes}`) {
+        throw new OpenGeniApiError(502, "retained screenshot range response is invalid");
+      }
+      bytes.set(page.bytes, start);
+    }
+    if (await sha256Hex(bytes) !== metadata.sha256) {
+      throw new OpenGeniApiError(502, "retained screenshot checksum mismatch");
+    }
+    return { metadata, bytes };
+  }
+  async getRetainedArtifactContentAtPath(path, options) {
     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 correlationId = crypto.randomUUID();
-    const response = await this.fetchImpl(
-      this.url(`/v1/workspaces/${workspaceId}/artifacts/${artifactId}/content`),
-      {
-        method: "GET",
-        headers: {
-          ...this.headers(correlationId),
-          Accept: "application/octet-stream",
-          ...options.range ? { Range: options.range } : {}
-        },
-        ...options.signal ? { signal: options.signal } : {}
-      }
-    );
+    const response = await this.fetchImpl(this.url(path), {
+      method: "GET",
+      headers: {
+        ...this.headers(correlationId),
+        Accept: "application/octet-stream",
+        ...options.range ? { Range: options.range } : {}
+      },
+      ...options.signal ? { signal: options.signal } : {}
+    });
     try {
       assertApiContractResponse(response);
     } catch (error) {
@@ -2843,7 +3109,10 @@ function isTranscribeAudioResponse(value) {
 function isUploadTranscriptionRecordingChunkResponse(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const record = value;
-  if (!isTranscriptionRecordingResponse({ recording: record.recording, segments: [] })) {
+  if (!isTranscriptionRecordingResponse({
+    recording: record.recording,
+    segments: []
+  })) {
     return false;
   }
   if (!record.chunk || typeof record.chunk !== "object" || Array.isArray(record.chunk)) {
@@ -2947,6 +3216,11 @@ async function sha256ForUpload(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 sha256Hex(bytes) {
+  const owned = Uint8Array.from(bytes);
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", owned.buffer);
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
 async function cancelResponseBody(response, reason) {
   await response.body?.cancel(reason).catch(() => void 0);
 }
@@ -3239,4 +3513,4 @@ export {
   authorizeTranscriptionAdapter,
   createTranscriptionSessionRequest
 };
-//# sourceMappingURL=chunk-QKV5OCLJ.js.map
+//# sourceMappingURL=chunk-MBGBLVUV.js.map