@opengeni/sdk 0.46.0 → 0.48.0

package/src/stream.ts

@@ -29,13 +29,25 @@ export type StreamSessionEventsOptions = {
   reconnectDelayMs?: number;
   /** Backoff ceiling. Defaults to 10s. */
   maxReconnectDelayMs?: number;
+  /** Random backoff spread as a fraction of the delay. Defaults to 0.2. */
+  reconnectJitterRatio?: number;
   /**
    * Give up after this many consecutive failed reconnect attempts (i.e. N
    * reconnects = N+1 total open-stream calls). Defaults to unlimited.
    */
   maxReconnectAttempts?: number;
+  /**
+   * Notify the consumer as soon as the SSE response body is open. This callback
+   * is deliberately synchronous and non-blocking: use it to start projection
+   * reconciliation without delaying consumption of live event bytes.
+   */
+  onOpen?: (() => void) | undefined;
   /** Await authoritative client reconciliation before exposing `live`. */
   beforeLive?: (() => void | Promise<void>) | undefined;
+  /** Maximum reconciliation time before reconnecting. Defaults to 15s. */
+  beforeLiveTimeoutMs?: number;
+  /** Maximum time without any SSE bytes before reconnecting. Defaults to 45s. */
+  heartbeatTimeoutMs?: number;
   onStateChange?: (state: StreamConnectionState) => void;
 };
 
@@ -62,6 +74,9 @@ export async function* streamSessionEvents(
   const reconnect = options.reconnect ?? true;
   const baseDelayMs = options.reconnectDelayMs ?? 500;
   const maxDelayMs = options.maxReconnectDelayMs ?? 10_000;
+  const jitterRatio = options.reconnectJitterRatio ?? 0.2;
+  const beforeLiveTimeoutMs = options.beforeLiveTimeoutMs ?? 15_000;
+  const heartbeatTimeoutMs = options.heartbeatTimeoutMs ?? 45_000;
   const maxAttempts = options.maxReconnectAttempts ?? Number.POSITIVE_INFINITY;
   let cursor = options.after ?? 0;
   let failedAttempts = 0;
@@ -77,9 +92,16 @@ export async function* streamSessionEvents(
       everConnected = true;
       failedAttempts = 0;
       delayMs = baseDelayMs;
-      await options.beforeLive?.();
+      try {
+        options.onOpen?.();
+      } catch {
+        // A notification observer cannot own or interrupt the event transport.
+      }
+      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),
+      )) {
         // Re-check after every yield resumption: an abort from the consumer
         // must not let already-buffered events keep flowing.
         if (signal?.aborted) {
@@ -108,7 +130,7 @@ export async function* streamSessionEvents(
       // progress (servers legitimately cycle long SSE connections); pace
       // empty closes so a misbehaving server is not hammered in a hot loop.
       if (cursor === cursorAtOpen) {
-        await sleep(baseDelayMs, signal);
+        await sleep(jitteredDelay(baseDelayMs, jitterRatio), signal);
       }
       continue;
     } catch (error) {
@@ -125,11 +147,87 @@ export async function* streamSessionEvents(
         );
       }
     }
-    await sleep(delayMs, signal);
+    await sleep(jitteredDelay(delayMs, jitterRatio), signal);
     delayMs = Math.min(Math.max(delayMs * 2, baseDelayMs), maxDelayMs);
   }
 }
 
+export async function runBeforeLive(
+  beforeLive: (() => void | Promise<void>) | undefined,
+  timeoutMs: number,
+  signal: AbortSignal | undefined,
+): Promise<void> {
+  if (!beforeLive) return;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let abortListener: (() => void) | undefined;
+  const timeout = new Promise<never>((_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 !== undefined) clearTimeout(timer);
+    if (signal && abortListener) signal.removeEventListener("abort", abortListener);
+  }
+}
+
+export function jitteredDelay(delayMs: number, ratio: number): number {
+  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);
+}
+
+export function withStreamInactivityTimeout(
+  stream: ReadableStream<Uint8Array>,
+  timeoutMs: number,
+  signal: AbortSignal | undefined,
+): ReadableStream<Uint8Array> {
+  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<Uint8Array>({
+    pull: async (controller) => {
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      let abortListener: (() => void) | undefined;
+      try {
+        const result = await Promise.race([
+          reader.read(),
+          new Promise<never>((_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 !== undefined) clearTimeout(timer);
+        if (signal && abortListener) signal.removeEventListener("abort", abortListener);
+      }
+    },
+    cancel: async (reason) => {
+      await reader.cancel(reason);
+    },
+  });
+}
+
 /**
  * Yield the durable events with `fromExclusive < sequence <= toInclusive`,
  * in order. Sequences are contiguous, so every one of them must exist in the

package/src/transcription.ts

@@ -159,7 +159,7 @@ export type TranscriptionResultMetadata = {
 export type TranscriptionDiagnostic = {
   operation: "start" | "session" | "cancel" | "close";
   code: TranscriptionErrorCode;
-  /** Diagnostic-only detail. React sanitizes and bounds this before forwarding it. */
+  /** Exact diagnostic detail forwarded by React without content rewriting. */
   detail: string;
 };
 
@@ -231,7 +231,7 @@ export type TranscriptionEventListener = (event: TranscriptionEvent) => void;
 export type TranscriptionAdapterStartContext = {
   /** Aborted on local cancellation, policy replacement, timeout, or unmount. */
   signal: AbortSignal;
-  /** Non-UI observability seam; callers receive only bounded, redacted detail. */
+  /** Non-UI observability seam; callers receive the exact provider detail. */
   reportDiagnostic: (diagnostic: TranscriptionDiagnostic) => void;
 };
 

package/src/types.ts

@@ -1587,6 +1587,8 @@ export type FsListResponse = {
   revision: number;
   truncated: boolean;
 };
+export type FsListBatchRequest = { requests: FsListRequest[] };
+export type FsListBatchResponse = { results: FsListResponse[] };
 export type FsReadRequest = {
   path: string;
   encoding?: FsEncoding;
@@ -1695,6 +1697,16 @@ export type GitDiffRequest = {
   maxBytesPerFile?: number;
 };
 export type GitDiffResponse = { files: GitFileDiff[]; revision: number };
+export type GitReadBatchItemRequest = {
+  status: GitStatusRequest;
+  diff?: GitDiffRequest;
+};
+export type GitReadBatchRequest = { requests: GitReadBatchItemRequest[] };
+export type GitReadBatchItemResponse = {
+  status: GitStatusResponse;
+  diff?: GitDiffResponse;
+};
+export type GitReadBatchResponse = { results: GitReadBatchItemResponse[] };
 export type GitLogRequest = {
   path?: string;
   ref?: string;
@@ -1755,6 +1767,9 @@ export type WorkspaceCaptureRepo = {
   behind: number;
   status: GitFileStatus[];
   diff: GitFileDiff[];
+  /** Current branch vs the remote default branch. Absent on legacy captures or
+   *  repositories whose remote default ref could not be resolved. */
+  branchDiff?: GitFileDiff[] | undefined;
 };
 export type WorkspaceCaptureDegradedReason =
   | "repository_discovery_command_failed"
@@ -1875,7 +1890,7 @@ export type SessionStructuredCapabilities = {
 
 export type ScheduledTaskStatus = "active" | "paused";
 
-export type ScheduledTaskRunMode = "new_session_per_run" | "reusable_session";
+export type ScheduledTaskRunMode = "new_session_per_run" | "reusable_session" | "existing_session";
 
 export type ScheduledTaskOverlapPolicy = "allow_concurrent" | "skip" | "buffer_one";
 
@@ -1931,6 +1946,7 @@ export type ScheduledTask = {
   createdBy?: TurnInitiator | undefined;
   createdByContext?: TurnInitiatorContext | undefined;
   personalConnections?: McpPersonalConnectionSummary[] | undefined;
+  targetSessionId: string | null;
   reusableSessionId: string | null;
   variableSetId: string | null;
   /** @deprecated use variableSetId */
@@ -2038,8 +2054,14 @@ export const 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",
@@ -2075,6 +2097,8 @@ export type FirstPartyMcpToolName =
   | "sandbox_swap"
   | "run_on"
   | "sandbox_provision"
+  | "connected_machine_remove"
+  | "connected_machine_remove"
   | "rig_list"
   | "rig_get"
   | "rig_propose_change"
@@ -2091,6 +2115,7 @@ export type FirstPartyMcpToolName =
   | "set_other_session_title"
   | "variable_set_list"
   | "environment_list"
+  | "variable_set_get_variable"
   | "variable_set_set_variable"
   | "environment_set_variable"
   | "github_connect_link"
@@ -2736,6 +2761,8 @@ export type WorkspaceSettings = {
   maxNestedAgentDepth?: number | null | undefined;
   /** Default for new Codex sessions; absent ⇒ remote_v2. */
   codexCompactionDefault?: "remote_v2" | "portable" | undefined;
+  /** Whether agents may invoke the built-in structured human-input tool. */
+  agentHumanInputEnabled?: boolean | undefined;
   slackReactionSummon?: WorkspaceSlackReactionSummonSettings | undefined;
   [key: string]: unknown;
 };
@@ -2767,6 +2794,7 @@ export type UpdateWorkspaceSettingsRequest = {
   transcription?: WorkspaceTranscriptionPolicy | undefined;
   maxNestedAgentDepth?: number | null | undefined;
   codexCompactionDefault?: "remote_v2" | "portable" | undefined;
+  agentHumanInputEnabled?: boolean | undefined;
   slackReactionSummon?: WorkspaceSlackReactionSummonSettings | undefined;
   [key: string]: unknown;
 };
@@ -3179,6 +3207,7 @@ export type CreateScheduledTaskRequest = {
   name: string;
   schedule: ScheduledTaskScheduleSpec;
   runMode?: ScheduledTaskRunMode | undefined;
+  targetSessionId?: string | null | undefined;
   overlapPolicy?: ScheduledTaskOverlapPolicy | undefined;
   agentConfig: ScheduledTaskAgentConfigInput;
   status?: ScheduledTaskStatus | undefined;
@@ -3194,6 +3223,7 @@ export type UpdateScheduledTaskRequest = {
   name?: string | undefined;
   schedule?: ScheduledTaskScheduleSpec | undefined;
   runMode?: ScheduledTaskRunMode | undefined;
+  targetSessionId?: string | null | undefined;
   overlapPolicy?: ScheduledTaskOverlapPolicy | undefined;
   agentConfig?: ScheduledTaskAgentConfigInput | undefined;
   status?: ScheduledTaskStatus | undefined;
@@ -3227,11 +3257,7 @@ export type ScheduledTaskRun = {
 
 // --- VariableSets -------------------------------------------------------------
 
-/**
- * Variable values are write-only by design: the API never returns a value, so
- * reads expose name + version metadata only. Values are decrypted exclusively
- * inside the worker at sandbox materialization time.
- */
+/** Generic variable-set reads expose name + version metadata only. */
 export type VariableSetVariableMetadata = {
   name: string;
   version: number;
@@ -3239,6 +3265,14 @@ export type VariableSetVariableMetadata = {
   updatedAt: string;
 };
 
+/** Dedicated permissioned plaintext response; never embedded in metadata reads. */
+export type VariableSetSecret = {
+  variableSetId: string;
+  name: string;
+  version: number;
+  value: string;
+};
+
 export type VariableSet = {
   id: string;
   accountId: string;
@@ -3412,12 +3446,14 @@ export type FileAsset = {
 /** Mirrors the closed, provider-neutral retained-output contract. */
 export const RETAINED_OUTPUT_DEFAULT_PAGE_BYTES = 256 * 1024;
 export const RETAINED_OUTPUT_MAX_PAGE_BYTES = 1024 * 1024;
+export const COMPUTER_SCREENSHOT_MAX_BYTES = 32 * 1024 * 1024;
 
 export type RetainedOutputKind =
   | "tool_result"
   | "assistant_completion"
   | "internal_update"
   | "event_media"
+  | "computer_screenshot"
   | "file";
 
 export type RetainedOutputUnavailableReason =
@@ -3428,6 +3464,9 @@ export type RetainedOutputUnavailableReason =
   | "deleted"
   | "missing_storage"
   | "storage_write_failed"
+  | "quota_exceeded"
+  | "invalid_content"
+  | "oversized"
   | "unsupported";
 
 export type RetainedArtifactReference = {
@@ -3438,7 +3477,10 @@ export type RetainedArtifactReference = {
   originalBytes: number;
   sha256: string;
   retainedAt: string;
-  retention: { policy: "workspace_file"; expiresAt: null };
+  dimensions?: { width: number; height: number } | undefined;
+  retention:
+    | { policy: "workspace_file"; expiresAt: null }
+    | { policy: "session_screenshot"; expiresAt: string };
   retrieval: {
     method: "GET";
     path: string;
@@ -3470,6 +3512,18 @@ export type RetainedArtifactContent = {
   acceptRanges: "bytes";
 };
 
+export type RetainedScreenshotDownloadOptions = {
+  signal?: AbortSignal | undefined;
+  /** Retry transient range failures; bounded to 0..3, default 2. */
+  maxRetries?: number | undefined;
+};
+
+export type RetainedScreenshotDownload = {
+  metadata: RetainedArtifactMetadata;
+  /** Null when metadata truth says the screenshot is unavailable. */
+  bytes: Uint8Array | null;
+};
+
 export type CreateFileUploadRequest = {
   filename: string;
   contentType: string;
@@ -3505,6 +3559,8 @@ export type UploadFileInput = {
   contentType: string;
   data: FileUploadData;
   sha256?: string | undefined;
+  /** Optional deadline for the signed object-storage PUT. */
+  timeoutMs?: number | undefined;
 };
 
 // --- Documents -------------------------------------------------------------------
@@ -4478,6 +4534,32 @@ export type MachineMetricsSeriesResponse = {
   samples: MetricSample[];
 };
 
+/** POST /v1/workspaces/:ws/enrollments/:id/revoke body. */
+export type RemoveEnrollmentRequest = {
+  expectedUpdatedAt?: string;
+  idempotencyKey?: string;
+};
+
+/** Typed removal/revocation outcome. Blocked outcomes preserve the exact
+ * dependency and the action needed to make removal safe. */
+export type RemoveEnrollmentResponse = {
+  revoked: boolean;
+  outcome: "removed" | "already_removed" | "blocked";
+  enrollmentId: string;
+  machineName: string | null;
+  lastSeenAt: string | null;
+  revokedAt: string | null;
+  code:
+    | "active_route"
+    | "active_commands"
+    | "active_lease"
+    | "recovery_pending"
+    | "not_selfhosted"
+    | null;
+  message: string;
+  action: string;
+};
+
 /** POST /v1/workspaces/:ws/sessions/:sessionId/active-sandbox — swap a session's
  *  active sandbox. `target` is a `MachineView.sandboxId`, or "session"/"default"
  *  to swap back to the session's own group box. */

package/src/workspace-control-stream.ts

@@ -1,6 +1,11 @@
 import { isAbortError, isRetryableStreamError, OpenGeniStreamError } from "./errors";
 import { parseSseStream } from "./sse";
-import type { StreamSessionEventsOptions } from "./stream";
+import {
+  jitteredDelay,
+  runBeforeLive,
+  type StreamSessionEventsOptions,
+  withStreamInactivityTimeout,
+} from "./stream";
 import type { WorkspaceControlEvent } from "./types";
 
 export type WorkspaceControlStreamTransport = {
@@ -24,6 +29,9 @@ export async function* streamWorkspaceControlEvents(
   const reconnect = options.reconnect ?? true;
   const baseDelayMs = options.reconnectDelayMs ?? 500;
   const maxDelayMs = options.maxReconnectDelayMs ?? 10_000;
+  const jitterRatio = options.reconnectJitterRatio ?? 0.2;
+  const beforeLiveTimeoutMs = options.beforeLiveTimeoutMs ?? 15_000;
+  const heartbeatTimeoutMs = options.heartbeatTimeoutMs ?? 45_000;
   const maxAttempts = options.maxReconnectAttempts ?? Number.POSITIVE_INFINITY;
   let cursor = options.after ?? 0;
   let failures = 0;
@@ -39,9 +47,11 @@ export async function* streamWorkspaceControlEvents(
       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;
@@ -49,7 +59,7 @@ export async function* streamWorkspaceControlEvents(
         yield event;
       }
       if (!reconnect) return;
-      if (cursor === cursorAtOpen) await sleep(baseDelayMs, signal);
+      if (cursor === cursorAtOpen) await sleep(jitteredDelay(baseDelayMs, jitterRatio), signal);
       continue;
     } catch (error) {
       if (signal?.aborted || isAbortError(error)) return;
@@ -63,7 +73,7 @@ export async function* streamWorkspaceControlEvents(
         );
       }
     }
-    await sleep(delayMs, signal);
+    await sleep(jitteredDelay(delayMs, jitterRatio), signal);
     delayMs = Math.min(Math.max(delayMs * 2, baseDelayMs), maxDelayMs);
   }
 }