@opengeni/sdk 0.15.0 → 0.23.0

package/dist/index.js

@@ -293,8 +293,11 @@ async function sleep2(delayMs, signal) {
 // src/types.ts
 var SESSION_EVENT_TYPES = [
   "session.created",
+  // Defensive bounded projection for malformed/legacy oversized envelopes.
+  "session.event.envelope_omitted",
   "session.status.changed",
   "session.requiresAction",
+  "session.humanInput.requested",
   "session.context.compaction.requested",
   "session.context.compacted",
   "session.context.compaction.skipped",
@@ -302,6 +305,7 @@ var SESSION_EVENT_TYPES = [
   "user.message",
   "user.pause",
   "user.approvalDecision",
+  "user.humanInputResponse",
   "turn.queued",
   "turn.started",
   "turn.completed",
@@ -315,8 +319,10 @@ var SESSION_EVENT_TYPES = [
   "agent.reasoning.delta",
   "agent.toolCall.created",
   "agent.toolCall.output",
+  "agent.model.request",
   "agent.model.usage",
   "tool.auth_needed",
+  "credential.auth_needed",
   "agent.updated",
   "rig.setup.started",
   "rig.setup.completed",
@@ -365,11 +371,12 @@ var SESSION_EVENT_TYPES = [
   "terminal.pty.output.delta",
   "terminal.pty.exited",
   "session.title_set",
+  "session.mcp.approval_policy.updated",
   // Multi-account Codex (P1): the session's inference account changed.
   "codex.account.switched",
-  // OPE-21 metadata-only per-turn credential selection audit.
+  // credential allocator metadata-only per-turn credential selection audit.
   "codex.credential.selected",
-  // OPE-21 durable zero-capacity wait lifecycle. These are system/runtime
+  // credential allocator durable zero-capacity wait lifecycle. These are system/runtime
   // events, never synthetic user messages.
   "codex.capacity.waiting",
   "codex.capacity.resumed",
@@ -410,7 +417,7 @@ var KNOWN_PERMISSIONS = [
   "sessions:create",
   "sessions:read",
   "sessions:control",
-  // Sandbox-surfacing (mirror of @opengeni/contracts Permission). stream:view is
+  // sandbox workspace (mirror of @opengeni/contracts Permission). stream:view is
   // strictly broader than sessions:read (un-redacted pixels); stream:control is
   // the never-granted-v1 raw-input plane; stream:acknowledge is the secret-leak
   // consent gate.
@@ -442,8 +449,10 @@ var KNOWN_PERMISSIONS = [
   "rigs:use",
   "rigs:manage"
 ];
-var OPENGENI_API_CONTRACT_REVISION = "2026-07-session-control-v1";
+var OPENGENI_API_CONTRACT_REVISION = "2026-07-turn-instructions-v1";
 var OPENGENI_API_CONTRACT_HEADER = "x-opengeni-api-contract";
+var RETAINED_OUTPUT_DEFAULT_PAGE_BYTES = 256 * 1024;
+var RETAINED_OUTPUT_MAX_PAGE_BYTES = 1024 * 1024;
 var KNOWN_USAGE_EVENT_TYPES = [
   "agent_run.created",
   "agent_run.completed",
@@ -490,6 +499,18 @@ var OpenGeniClient = class {
       request
     );
   }
+  /**
+   * 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, sessionId, serverId, request) {
+    return await this.requestJson(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/mcp-servers/${encodeURIComponent(serverId)}/approval-policy`,
+      request
+    );
+  }
   async listSessions(workspaceId, options = {}) {
     return await this.requestJson(
       "GET",
@@ -559,7 +580,8 @@ var OpenGeniClient = class {
       void 0,
       {
         ...options.sessionId !== void 0 ? { sessionId: options.sessionId } : {}
-      }
+      },
+      { signal: options.signal }
     );
   }
   /**
@@ -659,23 +681,95 @@ var OpenGeniClient = class {
   }
   // --- Events: replay, send, stream ----------------------------------------
   /**
-   * Replay durable events by sequence, ascending. `before` is exclusive and
-   * returns the newest matching window. With `compact`, consecutive delta runs
-   * may be coalesced; `payload.coalescedUntil` carries the run's last sequence
-   * for resume cursors.
+   * Return the events from one bounded page. With no cursor, this uses the safe
+   * semantic monitoring tail; pass explicit forensic options and a cursor for
+   * retained audit replay. Use `listEventPage` when projection, coverage, or
+   * resume-cursor facts are required.
    */
   async listEvents(workspaceId, sessionId, options = {}) {
-    return await this.requestJson(
-      "GET",
-      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/events`,
-      void 0,
+    return (await this.listEventPage(workspaceId, sessionId, options)).events;
+  }
+  async listEventPage(workspaceId, sessionId, options = {}) {
+    if (options.latest && ["includeTypes", "excludeTypes", "includeClasses", "excludeClasses"].some(
+      (name) => Object.prototype.hasOwnProperty.call(options, name)
+    )) {
+      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 = options.resultMode === "compact" ? null : options;
+    const response = await this.fetchImpl(
+      this.url(`/v1/workspaces/${workspaceId}/sessions/${sessionId}/events`, {
+        ...listOptions?.after !== void 0 ? { after: String(listOptions.after) } : {},
+        ...listOptions?.before !== void 0 ? { before: String(listOptions.before) } : {},
+        ...listOptions?.limit !== void 0 ? { limit: String(listOptions.limit) } : {},
+        ...listOptions?.compact ? { compact: "1" } : {},
+        ...options.mode ? { mode: options.mode } : {},
+        ...listOptions?.direction ? { direction: listOptions.direction } : {},
+        ...options.payloadMode ? { payloadMode: options.payloadMode } : {},
+        ...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(",") } : {},
+        ...listOptions?.excludeClasses?.length ? { excludeClasses: listOptions.excludeClasses.join(",") } : {},
+        ...options.latest ? { latest: options.latest } : {}
+      }),
       {
-        ...options.after !== void 0 ? { after: String(options.after) } : {},
-        ...options.before !== void 0 ? { before: String(options.before) } : {},
-        ...options.limit !== void 0 ? { limit: String(options.limit) } : {},
-        ...options.compact ? { compact: "1" } : {}
+        method: "GET",
+        headers: { ...this.headers(), Accept: "application/json" }
       }
     );
+    assertApiContractResponse(response);
+    if (!response.ok) throw new OpenGeniApiError(response.status, await safeText(response));
+    const body = await response.json();
+    if (options.resultMode === "compact") {
+      return body;
+    }
+    const events = body;
+    const integerHeader = (name) => {
+      const raw = response.headers.get(name);
+      if (raw === null) return null;
+      const value = Number(raw);
+      return Number.isSafeInteger(value) && value >= 0 ? value : null;
+    };
+    const mode = response.headers.get("X-OpenGeni-Event-Mode") === "forensic" ? "forensic" : "monitoring";
+    const direction = response.headers.get("X-OpenGeni-Event-Direction") === "after" ? "after" : "before";
+    const payloadHeader = response.headers.get("X-OpenGeni-Payload-Mode");
+    const payloadMode = payloadHeader === "none" || payloadHeader === "full" ? payloadHeader : "summary";
+    const first = integerHeader("X-OpenGeni-Covered-First");
+    const last = integerHeader("X-OpenGeni-Covered-Last");
+    const bytes = integerHeader("X-OpenGeni-Page-Bytes") ?? new TextEncoder().encode(JSON.stringify(events)).byteLength;
+    const maxBytes = integerHeader("X-OpenGeni-Page-Max-Bytes") ?? 1024 * 1024;
+    const truncatedByHeader = response.headers.get("X-OpenGeni-Truncated-By");
+    const truncatedBy = truncatedByHeader === "count" || truncatedByHeader === "bytes" || truncatedByHeader === "http_bytes" ? truncatedByHeader : null;
+    return {
+      events,
+      mode,
+      payloadMode,
+      direction,
+      bytes,
+      maxBytes,
+      truncated: response.headers.get("X-OpenGeni-Page-Truncated") === "true",
+      hasMore: response.headers.get("X-OpenGeni-Has-More") === "true",
+      truncatedBy,
+      coveredSequence: first === null || last === null ? null : { first, last },
+      nextAfter: integerHeader("X-OpenGeni-Next-After"),
+      nextBefore: integerHeader("X-OpenGeni-Next-Before"),
+      forensicExact: response.headers.get("X-OpenGeni-Forensic-Exact") === "true"
+    };
+  }
+  /**
+   * 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, sessionId, options = { latest: "terminal" }) {
+    return await this.listEventPage(workspaceId, sessionId, {
+      ...options,
+      resultMode: "compact"
+    });
   }
   /** POST a user/control event to the session. Returns the accepted event. */
   async sendEvent(workspaceId, sessionId, event) {
@@ -710,6 +804,28 @@ var OpenGeniClient = class {
       payload
     });
   }
+  async listHumanInputRequests(workspaceId, sessionId, options = {}) {
+    const result = await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/human-input-requests`,
+      void 0,
+      options.status ? { status: options.status } : void 0
+    );
+    return result.requests;
+  }
+  async getHumanInputRequest(workspaceId, sessionId, requestId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/human-input-requests/${requestId}`
+    );
+  }
+  async submitHumanInputResponse(workspaceId, sessionId, requestId, response, options = {}) {
+    return await this.sendEvent(workspaceId, sessionId, {
+      type: "user.humanInputResponse",
+      ...options.clientEventId ? { clientEventId: options.clientEventId } : {},
+      payload: { requestId, response }
+    });
+  }
   /**
    * Live-stream a session's events with automatic reconnect, resume from the
    * last seen sequence, gap backfill, and duplicate suppression. See
@@ -818,15 +934,35 @@ var OpenGeniClient = class {
     );
   }
   async listWorkspaceControlEvents(workspaceId, options = {}) {
-    return await this.requestJson(
-      "GET",
-      `/v1/workspaces/${workspaceId}/control-events`,
-      void 0,
-      {
+    return (await this.listWorkspaceControlEventPage(workspaceId, options)).events;
+  }
+  /** Count/byte-bounded page plus an explicit continuation cursor. */
+  async listWorkspaceControlEventPage(workspaceId, options = {}) {
+    const response = await this.fetchImpl(
+      this.url(`/v1/workspaces/${workspaceId}/control-events`, {
         ...options.after !== void 0 ? { after: String(options.after) } : {},
         ...options.limit !== void 0 ? { limit: String(options.limit) } : {}
+      }),
+      {
+        method: "GET",
+        headers: { ...this.headers(), Accept: "application/json" }
       }
     );
+    assertApiContractResponse(response);
+    if (!response.ok) {
+      throw new OpenGeniApiError(response.status, await safeText(response));
+    }
+    const events = await response.json();
+    const bytesHeader = response.headers.get("X-OpenGeni-Page-Bytes");
+    const nextHeader = response.headers.get("X-OpenGeni-Next-After");
+    const parsedBytes = bytesHeader === null ? Number.NaN : Number(bytesHeader);
+    const parsedNext = nextHeader === null ? null : Number(nextHeader);
+    return {
+      events,
+      bytes: Number.isSafeInteger(parsedBytes) && parsedBytes >= 0 ? parsedBytes : new TextEncoder().encode(JSON.stringify(events)).byteLength,
+      truncated: response.headers.get("X-OpenGeni-Page-Truncated") === "true",
+      nextAfter: parsedNext !== null && Number.isSafeInteger(parsedNext) && parsedNext >= 0 ? parsedNext : null
+    };
   }
   streamWorkspaceControlEvents(workspaceId, options = {}) {
     return streamWorkspaceControlEvents(this.workspaceControlStreamTransport(workspaceId), options);
@@ -926,19 +1062,23 @@ var OpenGeniClient = class {
   // synchronous API-direct point query; the fs.changed/git.changed/terminal.pty.*
   // notifications + the PTY output stream arrive on the existing event SSE.
   /** FileSystem: list a directory tree (feeds the Pierre file tree). */
-  async fsList(workspaceId, sessionId, request = {}) {
+  async fsList(workspaceId, sessionId, request = {}, options = {}) {
     return await this.requestJson(
       "POST",
       `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/list`,
-      request
+      request,
+      {},
+      options
     );
   }
   /** FileSystem: read a file (text or base64; binary-safe, size-capped). */
-  async fsRead(workspaceId, sessionId, request) {
+  async fsRead(workspaceId, sessionId, request, options = {}) {
     return await this.requestJson(
       "POST",
       `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/read`,
-      request
+      request,
+      {},
+      options
     );
   }
   /** FileSystem: write a file (last-writer-wins; emits fs.changed). */
@@ -974,19 +1114,23 @@ var OpenGeniClient = class {
     );
   }
   /** Git: working-tree/index status (the Pierre file-status feed). */
-  async gitStatus(workspaceId, sessionId, request = {}) {
+  async gitStatus(workspaceId, sessionId, request = {}, options = {}) {
     return await this.requestJson(
       "POST",
       `/v1/workspaces/${workspaceId}/sessions/${sessionId}/git/status`,
-      request
+      request,
+      {},
+      options
     );
   }
   /** Git: structured diff hunks (the Pierre diff feed). */
-  async gitDiff(workspaceId, sessionId, request = {}) {
+  async gitDiff(workspaceId, sessionId, request = {}, options = {}) {
     return await this.requestJson(
       "POST",
       `/v1/workspaces/${workspaceId}/sessions/${sessionId}/git/diff`,
-      request
+      request,
+      {},
+      options
     );
   }
   /** Git: commit log. */
@@ -1009,23 +1153,27 @@ var OpenGeniClient = class {
    *  (tree + per-repo diff + file after-image refs), served from durable storage
    *  WITHOUT warming a machine — the workbench cold-paint source. Returns
    *  `{available:false}` when no capture exists yet (fall back to the live path). */
-  async getWorkspaceCapture(workspaceId, sessionId) {
+  async getWorkspaceCapture(workspaceId, sessionId, options = {}) {
     return await this.requestJson(
       "GET",
-      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/workspace/capture`
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/workspace/capture`,
+      void 0,
+      {},
+      options
     );
   }
   /** Workspace capture: a single file's after-image from the capture (revision
    *  pins a specific one; omitted → latest). Content is inline for small files,
    *  else a short-TTL signed URL; a tooLarge file returns metadata only. */
-  async getWorkspaceCaptureFile(workspaceId, sessionId, path, revision) {
+  async getWorkspaceCaptureFile(workspaceId, sessionId, path, revision, options = {}) {
     const query = { path };
     if (revision !== void 0) query.revision = String(revision);
     return await this.requestJson(
       "GET",
       `/v1/workspaces/${workspaceId}/sessions/${sessionId}/workspace/capture/file`,
       void 0,
-      query
+      query,
+      options
     );
   }
   /** Terminal: run a bounded command, returning buffered stdout/stderr inline. */
@@ -1080,10 +1228,13 @@ var OpenGeniClient = class {
    *  liveness the client polls on while `cold`/`warming`. The desktop URL/token
    *  are minted in-process only when the box is warm AND the principal has
    *  acknowledged the un-redacted plane. */
-  async getStreamCapabilities(workspaceId, sessionId) {
+  async getStreamCapabilities(workspaceId, sessionId, options = {}) {
     return await this.requestJson(
       "GET",
-      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/stream-capabilities`
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/stream-capabilities`,
+      void 0,
+      {},
+      options
     );
   }
   /** Record the calling principal's acknowledgment of the un-redacted desktop
@@ -1146,6 +1297,13 @@ var OpenGeniClient = class {
     }
     return config;
   }
+  /** Authenticated model definitions plus workspace-specific selectability. */
+  async getWorkspaceModelCatalog(workspaceId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/model-catalog`
+    );
+  }
   /** The caller's access context: subject, account + workspace grants, defaults. */
   async getAccessContext() {
     return await this.requestJson("GET", "/v1/access/me");
@@ -1476,6 +1634,71 @@ var OpenGeniClient = class {
       `/v1/workspaces/${workspaceId}/files/${fileId}`
     );
   }
+  /** Read provider-neutral retained evidence metadata; never returns a storage location. */
+  async getRetainedArtifact(workspaceId, artifactId) {
+    return await this.requestJson(
+      "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, artifactId, 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 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;
+    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, fileId) {
     return await this.requestJson(
@@ -1727,14 +1950,13 @@ var OpenGeniClient = class {
     return logoAssetPath ? `${this.baseUrl}/v1/${logoAssetPath}` : null;
   }
   // --- GitHub ----------------------------------------------------------------------------------
-  /** GitHub App configuration status + a signed install URL when configured. */
+  /** GitHub App configuration status; install/link URLs are null while new binding is disabled. */
   async getGitHubApp(workspaceId) {
     return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/github/app`);
   }
   /**
-   * Browser entry point that plants the CSRF cookie and forwards to GitHub's
-   * install page. Open this in a browser (it redirects); `state` comes from
-   * `getGitHubApp().installUrl` or a github_connect_link tool.
+   * Compatibility URL for previously issued state. New installation binding is
+   * disabled, so the endpoint validates state and terminates with HTTP 410.
    */
   githubConnectUrl(workspaceId, state) {
     return this.url(`/v1/workspaces/${workspaceId}/github/connect`, { state });
@@ -1752,6 +1974,13 @@ var OpenGeniClient = class {
       `/v1/workspaces/${workspaceId}/github/repositories/sync`
     );
   }
+  /** Remove one workspace binding without uninstalling the GitHub App itself. */
+  async unlinkGitHubInstallation(workspaceId, installationId) {
+    await this.requestVoid(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/github/installations/${installationId}`
+    );
+  }
   /** Build a GitHub App manifest + the GitHub URL to submit it to. */
   async createGitHubAppManifest(workspaceId, request = {}) {
     return await this.requestJson(
@@ -1863,6 +2092,13 @@ var OpenGeniClient = class {
       `/v1/workspaces/${workspaceId}/codex/usage/refresh`
     );
   }
+  /** Live independently-settled quota + reset-credit overview for every account. */
+  async codexOverview(workspaceId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/codex/overview`
+    );
+  }
   /** Disconnect ALL accounts (legacy workspace-wide). Prefer `disconnectCodexAccount`. */
   async codexDisconnect(workspaceId) {
     return await this.requestJson(
@@ -1892,6 +2128,14 @@ var OpenGeniClient = class {
       patch
     );
   }
+  /** Toggle only NEW automatic allocations under independent allocator OCC. */
+  async setCodexAccountAllocator(workspaceId, accountId, input) {
+    return await this.requestJson(
+      "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, accountId) {
     return await this.requestJson(
@@ -1915,7 +2159,7 @@ var OpenGeniClient = class {
       { target }
     );
   }
-  async requestJson(method, path, body, query = {}) {
+  async requestJson(method, path, body, query = {}, options = {}) {
     const response = await this.fetchImpl(this.url(path, query), {
       method,
       headers: {
@@ -1923,7 +2167,8 @@ var OpenGeniClient = class {
         Accept: "application/json",
         ...body !== void 0 ? { "Content-Type": "application/json" } : {}
       },
-      ...body !== void 0 ? { body: JSON.stringify(body) } : {}
+      ...body !== void 0 ? { body: JSON.stringify(body) } : {},
+      ...options.signal ? { signal: options.signal } : {}
     });
     assertApiContractResponse(response);
     if (!response.ok) {
@@ -1961,6 +2206,62 @@ async function safeText(response) {
     return "";
   }
 }
+async function safeBoundedText(response) {
+  try {
+    return new TextDecoder().decode(await readBoundedResponseBytes(response, 64 * 1024, null));
+  } catch {
+    return "";
+  }
+}
+async function cancelResponseBody(response, reason) {
+  await response.body?.cancel(reason).catch(() => void 0);
+}
+function parseBoundedContentLength(value) {
+  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, maxBytes, expectedBytes) {
+  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 = [];
+  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(() => void 0);
+        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;
+}
 
 // src/proxy.ts
 function formatSseEvent(event) {
@@ -2144,7 +2445,221 @@ function ttydInputFrame(data) {
 function ttydResizeFrame(columns, rows) {
   return TtydClientCommand.RESIZE + JSON.stringify({ columns, rows });
 }
+
+// src/transcription.ts
+var DEFAULT_WORKSPACE_TRANSCRIPTION_POLICY = {
+  enabled: false,
+  acceptanceId: null,
+  primary: null,
+  language: null,
+  autoDetectLanguage: false,
+  diarization: { enabled: false, maxSpeakers: null },
+  retention: { mode: "none", maxDays: null },
+  privacy: { allowProviderLogging: false, allowProviderTraining: false },
+  fallback: { mode: "disabled", targets: [] },
+  cost: { currency: "USD", maxPerHour: null, maxPerMonth: null }
+};
+function resolveWorkspaceTranscriptionPolicy(settings) {
+  if (!isRecord(settings)) return cloneDefaultPolicy();
+  const candidate = settings.transcription;
+  if (!isWorkspaceTranscriptionPolicy(candidate)) return cloneDefaultPolicy();
+  return {
+    ...candidate,
+    primary: candidate.primary ? normalizeTarget(candidate.primary) : null,
+    language: candidate.language?.trim() ?? null,
+    diarization: { ...candidate.diarization },
+    retention: { ...candidate.retention },
+    privacy: { ...candidate.privacy },
+    fallback: {
+      mode: candidate.fallback.mode,
+      targets: candidate.fallback.targets.map(normalizeTarget)
+    },
+    cost: { ...candidate.cost }
+  };
+}
+function authorizeTranscriptionAdapter(policy, descriptor, selection = { kind: "primary" }) {
+  if (!isWorkspaceTranscriptionPolicy(policy)) {
+    return { authorized: false, reason: "unaccepted" };
+  }
+  if (!policy.enabled) return { authorized: false, reason: "disabled" };
+  if (!policy.acceptanceId) return { authorized: false, reason: "unaccepted" };
+  let target;
+  if (selection.kind === "primary") {
+    target = policy.primary;
+  } else {
+    if (policy.fallback.mode !== "explicit") {
+      return { authorized: false, reason: "fallback_disabled" };
+    }
+    target = policy.fallback.targets[selection.index];
+    if (!target) return { authorized: false, reason: "fallback_unaccepted" };
+  }
+  if (!target) return { authorized: false, reason: "target_missing" };
+  const acceptedTarget = normalizeTarget(target);
+  if (acceptedTarget.provider !== descriptor.provider) {
+    return { authorized: false, reason: "provider_mismatch" };
+  }
+  if (acceptedTarget.model !== descriptor.model) {
+    return { authorized: false, reason: "model_mismatch" };
+  }
+  if (acceptedTarget.credentialMode !== descriptor.credentialMode) {
+    return { authorized: false, reason: "credential_mode_mismatch" };
+  }
+  if (acceptedTarget.region !== descriptor.region) {
+    return { authorized: false, reason: "region_mismatch" };
+  }
+  return {
+    authorized: true,
+    acceptanceId: policy.acceptanceId,
+    target: acceptedTarget,
+    selection
+  };
+}
+function createTranscriptionSessionRequest(input) {
+  const sequenceFloor = input.sequenceFloor ?? 0;
+  if (!Number.isSafeInteger(sequenceFloor) || sequenceFloor < 0) return null;
+  const authorization = authorizeTranscriptionAdapter(
+    input.policy,
+    input.adapter.descriptor,
+    input.selection
+  );
+  if (!authorization.authorized) return null;
+  return {
+    localSessionId: input.localSessionId,
+    policyAcceptanceId: authorization.acceptanceId,
+    selection: authorization.selection,
+    target: { ...authorization.target },
+    language: input.policy.language?.trim() ?? null,
+    autoDetectLanguage: input.policy.autoDetectLanguage,
+    diarization: { ...input.policy.diarization },
+    retention: { ...input.policy.retention },
+    privacy: { ...input.policy.privacy },
+    cost: { ...input.policy.cost },
+    sequenceFloor
+  };
+}
+function cloneDefaultPolicy() {
+  return {
+    ...DEFAULT_WORKSPACE_TRANSCRIPTION_POLICY,
+    diarization: { ...DEFAULT_WORKSPACE_TRANSCRIPTION_POLICY.diarization },
+    retention: { ...DEFAULT_WORKSPACE_TRANSCRIPTION_POLICY.retention },
+    privacy: { ...DEFAULT_WORKSPACE_TRANSCRIPTION_POLICY.privacy },
+    fallback: { mode: "disabled", targets: [] },
+    cost: { ...DEFAULT_WORKSPACE_TRANSCRIPTION_POLICY.cost }
+  };
+}
+function isWorkspaceTranscriptionPolicy(value) {
+  if (!isRecord(value) || typeof value.enabled !== "boolean") return false;
+  if (!hasOnlyKeys(value, [
+    "enabled",
+    "acceptanceId",
+    "primary",
+    "language",
+    "autoDetectLanguage",
+    "diarization",
+    "retention",
+    "privacy",
+    "fallback",
+    "cost"
+  ])) {
+    return false;
+  }
+  if (!(value.acceptanceId === null || isUuid(value.acceptanceId))) return false;
+  if (!(value.primary === null || isTarget(value.primary))) return false;
+  if (!(value.language === null || isBoundedString(value.language, 64))) return false;
+  if (typeof value.autoDetectLanguage !== "boolean") return false;
+  if (!isRecord(value.diarization) || !hasOnlyKeys(value.diarization, ["enabled", "maxSpeakers"]) || typeof value.diarization.enabled !== "boolean" || !(value.diarization.maxSpeakers === null || isBoundedInteger(value.diarization.maxSpeakers, 100) && value.diarization.maxSpeakers >= 2)) {
+    return false;
+  }
+  if (!value.diarization.enabled && value.diarization.maxSpeakers !== null) return false;
+  if (!isRecord(value.retention) || !hasOnlyKeys(value.retention, ["mode", "maxDays"])) {
+    return false;
+  }
+  if (value.retention.mode !== "none" && value.retention.mode !== "provider-policy") return false;
+  if (!(value.retention.maxDays === null || isBoundedInteger(value.retention.maxDays, 3650))) {
+    return false;
+  }
+  if (!isRecord(value.privacy) || !hasOnlyKeys(value.privacy, ["allowProviderLogging", "allowProviderTraining"]) || typeof value.privacy.allowProviderLogging !== "boolean" || typeof value.privacy.allowProviderTraining !== "boolean") {
+    return false;
+  }
+  if (!isRecord(value.fallback) || !hasOnlyKeys(value.fallback, ["mode", "targets"])) {
+    return false;
+  }
+  if (value.fallback.mode !== "disabled" && value.fallback.mode !== "explicit") return false;
+  if (!Array.isArray(value.fallback.targets) || value.fallback.targets.length > 8 || !value.fallback.targets.every(isTarget)) {
+    return false;
+  }
+  if (value.fallback.mode === "disabled" && value.fallback.targets.length !== 0) return false;
+  if (value.fallback.mode === "explicit" && value.fallback.targets.length === 0) return false;
+  if (!isRecord(value.cost) || !hasOnlyKeys(value.cost, ["currency", "maxPerHour", "maxPerMonth"]) || value.cost.currency !== "USD") {
+    return false;
+  }
+  if (!isNullableBoundedNumber(value.cost.maxPerHour, 1e4)) return false;
+  if (!isNullableBoundedNumber(value.cost.maxPerMonth, 1e6)) return false;
+  if (value.enabled && (!value.acceptanceId || !value.primary)) return false;
+  if (value.enabled && !value.autoDetectLanguage && value.language === null) return false;
+  if (value.autoDetectLanguage && value.language !== null) return false;
+  const targets = [value.primary, ...value.fallback.targets].filter(
+    (target) => target !== null
+  );
+  if (new Set(targets.map(targetKey)).size !== targets.length) return false;
+  return true;
+}
+function targetKey(target) {
+  return [
+    target.provider.trim(),
+    target.model?.trim() ?? "",
+    target.credentialMode,
+    target.credentialConnectionId ?? "",
+    target.region?.trim() ?? ""
+  ].join("\0");
+}
+function isTarget(value) {
+  if (!isRecord(value)) return false;
+  if (!hasOnlyKeys(value, ["provider", "model", "credentialMode", "credentialConnectionId", "region"])) {
+    return false;
+  }
+  if (!isBoundedString(value.provider, 128)) return false;
+  if (!(value.model === null || isBoundedString(value.model, 256))) return false;
+  if (value.credentialMode !== "managed" && value.credentialMode !== "byok") return false;
+  if (value.provider.trim() === "azure-speech" && value.credentialMode !== "byok") return false;
+  if (!(value.credentialConnectionId === null || isUuid(value.credentialConnectionId))) {
+    return false;
+  }
+  if (!(value.region === null || isBoundedString(value.region, 128))) return false;
+  if (value.credentialMode === "byok" && value.credentialConnectionId === null) return false;
+  if (value.credentialMode === "managed" && value.credentialConnectionId !== null) return false;
+  return true;
+}
+function normalizeTarget(target) {
+  return {
+    provider: target.provider.trim(),
+    model: target.model?.trim() ?? null,
+    credentialMode: target.credentialMode,
+    credentialConnectionId: target.credentialConnectionId,
+    region: target.region?.trim() ?? null
+  };
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function hasOnlyKeys(value, keys) {
+  const accepted = new Set(keys);
+  return Object.keys(value).every((key) => accepted.has(key));
+}
+function isBoundedString(value, maximum) {
+  return typeof value === "string" && value.trim().length > 0 && value.length <= maximum;
+}
+function isUuid(value) {
+  return typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+function isBoundedInteger(value, maximum) {
+  return Number.isInteger(value) && value >= 0 && value <= maximum;
+}
+function isNullableBoundedNumber(value, maximum) {
+  return value === null || typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= maximum;
+}
 export {
+  DEFAULT_WORKSPACE_TRANSCRIPTION_POLICY,
   KNOWN_PERMISSIONS,
   KNOWN_USAGE_EVENT_TYPES,
   OPENGENI_API_CONTRACT_HEADER,
@@ -2153,17 +2668,22 @@ export {
   OpenGeniApiError,
   OpenGeniClient,
   OpenGeniStreamError,
+  RETAINED_OUTPUT_DEFAULT_PAGE_BYTES,
+  RETAINED_OUTPUT_MAX_PAGE_BYTES,
   SESSION_EVENT_TYPES,
   TTYD_SUBPROTOCOL,
   TtydClientCommand,
   TtydServerCommand,
   applyUrlRotation,
+  authorizeTranscriptionAdapter,
+  createTranscriptionSessionRequest,
   desktopSocketUrl,
   formatSseEvent,
   isRetryableStreamError,
   nextDesktopState,
   parseSseStream,
   proxySessionEventStream,
+  resolveWorkspaceTranscriptionPolicy,
   resumeSequenceFromRequest,
   sessionEventsToSseResponse,
   sessionEventsToSseStream,