@opengeni/sdk 0.32.1 → 0.33.1

package/dist/chunk-YROWFD7R.js

@@ -0,0 +1,2971 @@
+// src/errors.ts
+var OpenGeniApiError = class extends Error {
+  status;
+  code;
+  retryable;
+  correlationId;
+  /** True only when an uncontrolled transport failed after a mutation may have been accepted. */
+  outcomeUnknown;
+  body;
+  constructor(status, body, options = {}) {
+    const decoded = decodeApiErrorBody(body);
+    const correlationId = decoded?.requestId ?? boundedCorrelationId(options.correlationId);
+    const gatewayFailure = status >= 502 && status <= 504;
+    const fromResponse = options.mutation !== void 0;
+    const message = decoded?.message ?? (fromResponse ? "Request failed." : body || "(empty body)");
+    const displayMessage = options.displayMessage ?? (gatewayFailure && fromResponse ? "OpenGeni is temporarily unavailable \u2014 retry." : `OpenGeni API ${status}: ${message}`);
+    super(correlationId ? `${displayMessage} Reference: ${correlationId}.` : displayMessage);
+    this.name = "OpenGeniApiError";
+    this.status = status;
+    this.code = options.code ?? decoded?.code ?? (gatewayFailure && fromResponse ? "upstream_unavailable" : void 0);
+    this.retryable = options.retryable ?? decoded?.retryable ?? retryableApiStatus(status);
+    this.correlationId = correlationId;
+    this.outcomeUnknown = options.outcomeUnknown ?? (gatewayFailure && !!options.mutation && !decoded);
+    this.body = !fromResponse || decoded ? body : "";
+  }
+};
+function decodeApiErrorBody(body) {
+  if (!body) return null;
+  try {
+    const decoded = JSON.parse(body);
+    if (!decoded || typeof decoded !== "object" || Array.isArray(decoded)) return null;
+    const record = decoded;
+    const nested = record.error && typeof record.error === "object" && !Array.isArray(record.error) ? record.error : record;
+    const code = boundedApiField(nested.code);
+    const message = boundedApiField(nested.message);
+    const requestId = boundedCorrelationId(nested.requestId);
+    const retryable = typeof nested.retryable === "boolean" ? nested.retryable : void 0;
+    if (!code && !message && !requestId && retryable === void 0) return null;
+    return {
+      code,
+      message,
+      requestId,
+      retryable
+    };
+  } catch {
+    return null;
+  }
+}
+function boundedApiField(value) {
+  if (typeof value !== "string") return;
+  const bytes = new TextEncoder().encode(value);
+  return bytes.byteLength <= 512 ? value : new TextDecoder().decode(bytes.slice(0, 512));
+}
+function retryableApiStatus(status) {
+  return status === 408 || status === 409 || status === 425 || status === 429 || status >= 500;
+}
+function boundedCorrelationId(value) {
+  if (typeof value !== "string" || value.length > 128 || !/^[\w.:-]+$/.test(value)) {
+    return;
+  }
+  return value;
+}
+var OpenGeniSessionListCursorError = class extends OpenGeniApiError {
+};
+var OpenGeniApiContractMismatchError = class extends Error {
+  expected;
+  actual;
+  constructor(expected, actual) {
+    super(`OpenGeni API contract mismatch: client expects ${expected}, API serves ${actual}`);
+    this.name = "OpenGeniApiContractMismatchError";
+    this.expected = expected;
+    this.actual = actual;
+  }
+};
+var OpenGeniStreamError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "OpenGeniStreamError";
+  }
+};
+function isAbortError(error) {
+  return error instanceof DOMException && error.name === "AbortError" || error instanceof Error && error.name === "AbortError";
+}
+function isRetryableStreamError(error) {
+  if (error instanceof OpenGeniApiError) return error.retryable;
+  return error instanceof TypeError;
+}
+
+// src/sse.ts
+async function* parseSseStream(stream) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let id;
+  let event;
+  let dataLines = null;
+  const dispatch = () => {
+    const message = dataLines === null ? null : {
+      ...id !== void 0 ? { id } : {},
+      ...event !== void 0 ? { event } : {},
+      data: dataLines.join("\n")
+    };
+    id = void 0;
+    event = void 0;
+    dataLines = null;
+    return message;
+  };
+  const handleLine = (line) => {
+    if (line === "") {
+      return dispatch();
+    }
+    if (line.startsWith(":")) {
+      return null;
+    }
+    const colon = line.indexOf(":");
+    const field = colon === -1 ? line : line.slice(0, colon);
+    let value = colon === -1 ? "" : line.slice(colon + 1);
+    if (value.startsWith(" ")) {
+      value = value.slice(1);
+    }
+    if (field === "data") {
+      (dataLines ??= []).push(value);
+    } else if (field === "event") {
+      event = value;
+    } else if (field === "id") {
+      id = value;
+    }
+    return null;
+  };
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      buffer += decoder.decode(value, { stream: true });
+      let newline = buffer.indexOf("\n");
+      while (newline !== -1) {
+        let line = buffer.slice(0, newline);
+        buffer = buffer.slice(newline + 1);
+        if (line.endsWith("\r")) {
+          line = line.slice(0, -1);
+        }
+        const message = handleLine(line);
+        if (message) {
+          yield message;
+        }
+        newline = buffer.indexOf("\n");
+      }
+    }
+  } finally {
+    await reader.cancel().catch(() => {
+    });
+    reader.releaseLock();
+  }
+}
+
+// src/stream.ts
+async function* streamSessionEvents(transport, options = {}) {
+  const signal = options.signal;
+  const reconnect = options.reconnect ?? true;
+  const baseDelayMs = options.reconnectDelayMs ?? 500;
+  const maxDelayMs = options.maxReconnectDelayMs ?? 1e4;
+  const maxAttempts = options.maxReconnectAttempts ?? Number.POSITIVE_INFINITY;
+  let cursor = options.after ?? 0;
+  let failedAttempts = 0;
+  let delayMs = baseDelayMs;
+  let everConnected = false;
+  while (true) {
+    if (signal?.aborted) break;
+    options.onStateChange?.(everConnected || failedAttempts > 0 ? "reconnecting" : "connecting");
+    const cursorAtOpen = cursor;
+    try {
+      const body = await transport.openStream(cursor, signal);
+      everConnected = true;
+      failedAttempts = 0;
+      delayMs = baseDelayMs;
+      await options.beforeLive?.();
+      options.onStateChange?.("live");
+      for await (const message of parseSseStream(body)) {
+        if (signal?.aborted) {
+          return;
+        }
+        const event = parseSessionEvent(message.data);
+        if (!event || event.sequence <= cursor) {
+          continue;
+        }
+        if (event.sequence > cursor + 1) {
+          for await (const missed of backfillEvents(transport, cursor, event.sequence - 1)) {
+            cursor = missed.sequence;
+            yield missed;
+            if (signal?.aborted) {
+              return;
+            }
+          }
+        }
+        cursor = event.sequence;
+        yield event;
+      }
+      if (!reconnect) {
+        return;
+      }
+      if (cursor === cursorAtOpen) {
+        await sleep(baseDelayMs, signal);
+      }
+      continue;
+    } catch (error) {
+      if (signal?.aborted || isAbortError(error)) {
+        return;
+      }
+      if (!reconnect || !isRetryableStreamError(error)) {
+        throw error;
+      }
+      failedAttempts += 1;
+      if (failedAttempts > maxAttempts) {
+        throw new OpenGeniStreamError(
+          `event stream gave up after ${maxAttempts} consecutive failed reconnect attempts: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+    await sleep(delayMs, signal);
+    delayMs = Math.min(Math.max(delayMs * 2, baseDelayMs), maxDelayMs);
+  }
+}
+async function* backfillEvents(transport, fromExclusive, toInclusive) {
+  let cursor = fromExclusive;
+  while (cursor < toInclusive) {
+    const page = await transport.listEvents(cursor, Math.min(500, toInclusive - cursor));
+    const advancing = page.filter((event) => event.sequence > cursor && event.sequence <= toInclusive).sort((a, b) => a.sequence - b.sequence);
+    if (advancing.length === 0) {
+      throw new OpenGeniStreamError(
+        `event replay backfill stalled: expected sequences ${cursor + 1}..${toInclusive} but the replay endpoint returned none of them`
+      );
+    }
+    for (const event of advancing) {
+      if (event.sequence !== cursor + 1) {
+        throw new OpenGeniStreamError(
+          `event replay backfill is missing sequence ${cursor + 1} (replay endpoint skipped to ${event.sequence}); refusing to deliver with a gap`
+        );
+      }
+      cursor = event.sequence;
+      yield event;
+    }
+  }
+}
+function parseSessionEvent(data) {
+  let parsed;
+  try {
+    parsed = JSON.parse(data);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null || typeof parsed.sequence !== "number" || typeof parsed.type !== "string" || typeof parsed.id !== "string") {
+    return null;
+  }
+  return parsed;
+}
+async function sleep(delayMs, signal) {
+  if (signal?.aborted || delayMs <= 0) {
+    return;
+  }
+  await new Promise((resolve) => {
+    const timer = setTimeout(done, delayMs);
+    function done() {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", done);
+      resolve();
+    }
+    signal?.addEventListener("abort", done, { once: true });
+  });
+}
+
+// src/workspace-control-stream.ts
+async function* streamWorkspaceControlEvents(transport, options = {}) {
+  const signal = options.signal;
+  const reconnect = options.reconnect ?? true;
+  const baseDelayMs = options.reconnectDelayMs ?? 500;
+  const maxDelayMs = options.maxReconnectDelayMs ?? 1e4;
+  const maxAttempts = options.maxReconnectAttempts ?? Number.POSITIVE_INFINITY;
+  let cursor = options.after ?? 0;
+  let failures = 0;
+  let delayMs = baseDelayMs;
+  let everConnected = false;
+  for (; ; ) {
+    if (signal?.aborted) return;
+    options.onStateChange?.(everConnected || failures > 0 ? "reconnecting" : "connecting");
+    const cursorAtOpen = cursor;
+    try {
+      const body = await transport.openStream(cursor, signal);
+      everConnected = true;
+      failures = 0;
+      delayMs = baseDelayMs;
+      await options.beforeLive?.();
+      options.onStateChange?.("live");
+      for await (const message of parseSseStream(body)) {
+        if (signal?.aborted) return;
+        const event = parseWorkspaceControlEvent(message.data);
+        if (!event || event.sequence <= cursor) continue;
+        cursor = event.sequence;
+        yield event;
+      }
+      if (!reconnect) return;
+      if (cursor === cursorAtOpen) await sleep2(baseDelayMs, signal);
+      continue;
+    } catch (error) {
+      if (signal?.aborted || isAbortError(error)) return;
+      if (!reconnect || !isRetryableStreamError(error)) throw error;
+      failures += 1;
+      if (failures > maxAttempts) {
+        throw new OpenGeniStreamError(
+          `workspace control stream gave up after ${maxAttempts} reconnect attempts: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+    await sleep2(delayMs, signal);
+    delayMs = Math.min(Math.max(delayMs * 2, baseDelayMs), maxDelayMs);
+  }
+}
+function parseWorkspaceControlEvent(data) {
+  let value;
+  try {
+    value = JSON.parse(data);
+  } catch {
+    return null;
+  }
+  if (typeof value !== "object" || value === null || value.type !== "workspace.control.changed" || typeof value.id !== "string" || typeof value.sequence !== "number") {
+    return null;
+  }
+  return value;
+}
+async function sleep2(delayMs, signal) {
+  if (signal?.aborted || delayMs <= 0) return;
+  await new Promise((resolve) => {
+    const timer = setTimeout(done, delayMs);
+    function done() {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", done);
+      resolve();
+    }
+    signal?.addEventListener("abort", done, { once: true });
+  });
+}
+
+// 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.compaction.started",
+  "session.context.compacted",
+  "session.context.compaction.skipped",
+  "session.context.cleared",
+  "user.message",
+  "user.pause",
+  "user.approvalDecision",
+  "user.humanInputResponse",
+  "turn.queued",
+  "turn.started",
+  "turn.completed",
+  "turn.failed",
+  "turn.cancelled",
+  "turn.superseded",
+  "turn.recovery.requested",
+  "turn.capacity_waiting",
+  "agent.message.delta",
+  "agent.message.completed",
+  "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",
+  "rig.setup.skipped",
+  "rig.setup.failed",
+  "sandbox.operation.started",
+  "sandbox.operation.completed",
+  "sandbox.operation.failed",
+  "sandbox.command.output.delta",
+  "artifact.created",
+  "goal.set",
+  "goal.updated",
+  "goal.completed",
+  "goal.paused",
+  "goal.resumed",
+  "goal.cleared",
+  "goal.continuation",
+  "system.update.pending",
+  "system.update.delivered",
+  "system.update.superseded",
+  "system.update.cancelled",
+  "system.update.settled",
+  "session.control.paused",
+  "session.control.resumed",
+  "session.control.steer_requested",
+  "workspace.inference.paused",
+  "workspace.inference.resumed",
+  "session.queue.changed",
+  "session.queue.prompt.cancelled",
+  "session.queue.history",
+  "turn.event.rejected_late",
+  "memory.saved",
+  "memory.corrected",
+  // Channel-B desktop pixel-plane signals (mirror of contracts SessionEventType;
+  // the contract-parity test asserts sorted equality).
+  "stream.url.rotated",
+  "stream.opened",
+  "stream.closed",
+  "stream.revoked",
+  // Channel-B recording signals (P4.3 — "agent films itself proving the fix").
+  "recording.started",
+  "recording.available",
+  "recording.failed",
+  // Channel-A structured-service notifications (P4.4; mirror of contracts
+  // SessionEventType — the contract-parity test asserts sorted equality).
+  "fs.changed",
+  "git.changed",
+  "terminal.pty.started",
+  "terminal.pty.output.delta",
+  "terminal.pty.exited",
+  "session.title_set",
+  "session.mcp.approval_policy.updated",
+  "session.tool_policy.updated",
+  // Multi-account Codex (P1): the session's inference account changed.
+  "codex.account.switched",
+  // credential allocator metadata-only per-turn credential selection audit.
+  "codex.credential.selected",
+  // Bounded, identity-free deterministic shadow/replay decision.
+  "codex.fleet.decision",
+  // credential allocator durable zero-capacity wait lifecycle. These are system/runtime
+  // events, never synthetic user messages.
+  "codex.capacity.waiting",
+  "codex.capacity.resumed",
+  "codex.capacity.superseded",
+  // Sandbox durability observability (mirror of contracts SessionEventType):
+  // box lifecycle + manifest-env drift, attributable from the DB alone.
+  "sandbox.box.created",
+  "sandbox.box.lost",
+  "sandbox.box.terminated",
+  "sandbox.box.snapshot",
+  "sandbox.env.drift",
+  // Active-sandbox pointer reconcile (issue #341; announce-only; mirror of contracts
+  // SessionEventType — the contract-parity test asserts sorted equality).
+  "session.route.reconciled",
+  // Workbench v2 turn-end workspace capture (announce-only; mirror of contracts
+  // SessionEventType — the contract-parity test asserts sorted equality).
+  "workspace.revision.captured",
+  "workspace.revision.degraded",
+  // Connected Machine op-outcome observability (announce-only, quiet; mirror of
+  // contracts SessionEventType — the contract-parity test asserts sorted equality).
+  "machine.op.failed",
+  "machine.op.recovered",
+  // Connected Machine link-plane observability (announce-only, quiet; mirror of
+  // contracts SessionEventType — the contract-parity test asserts sorted equality).
+  "machine.link.lost",
+  "machine.link.restored",
+  "machine.runner.restarted"
+];
+var KNOWN_PERMISSIONS = [
+  "account:read",
+  "account:admin",
+  "members:manage",
+  "workspace:create",
+  "billing:read",
+  "billing:manage",
+  "workspace:read",
+  "workspace:admin",
+  "sessions:create",
+  "sessions:read",
+  "sessions:control",
+  // 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.
+  "stream:view",
+  "stream:control",
+  "stream:acknowledge",
+  "files:upload",
+  "files:read",
+  "files:write",
+  "terminal:attach",
+  "documents:manage",
+  "documents:search",
+  "scheduled_tasks:manage",
+  "scheduled_tasks:run",
+  "github:manage",
+  "github:use",
+  "api_keys:manage",
+  "connections:read",
+  "connections:write",
+  "environments:manage",
+  "environments:use",
+  "variable-sets:manage",
+  "variable-sets:use",
+  "mcp_servers:attach",
+  "toolspace:call",
+  "goals:manage",
+  "enrollments:read",
+  "enrollments:manage",
+  "rigs:use",
+  "rigs:manage",
+  "artifacts:read",
+  "artifacts:publish"
+];
+var OPENGENI_API_CONTRACT_REVISION = "2026-07-workspace-artifacts-v1";
+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 KNOWN_USAGE_EVENT_TYPES = [
+  "agent_run.created",
+  "agent_run.completed",
+  "model.tokens",
+  "model.cost",
+  "file.uploaded",
+  "file.deleted",
+  "document.indexed",
+  "scheduled_task.fired",
+  "api_key.request",
+  // sandbox warm-time metering (P2.1) — mirrors contracts UsageEventType.
+  "sandbox.warm_seconds",
+  "sandbox.warm_cost"
+];
+
+// src/client.ts
+function sessionListQuery(options) {
+  const { limit, parentSessionId } = options;
+  return {
+    ...limit === void 0 ? {} : { limit: String(limit) },
+    ...parentSessionId === void 0 ? {} : { parentSessionId: parentSessionId ?? "null" }
+  };
+}
+var OpenGeniClient = class {
+  baseUrl;
+  options;
+  fetchImpl;
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.options = options;
+    this.fetchImpl = options.fetch ?? ((input, init) => fetch(input, init));
+  }
+  // --- Session lifecycle ---------------------------------------------------
+  /** Upload one ephemeral browser recording. This method never retries. */
+  async transcribeAudio(workspaceId, input) {
+    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 });
+    form.append("audio", audio, filename);
+    form.append("mimeType", input.mimeType);
+    if (input.durationSeconds !== void 0) {
+      form.append("durationSeconds", String(input.durationSeconds));
+    }
+    let response;
+    try {
+      response = await this.fetchImpl(this.url(`/v1/workspaces/${workspaceId}/transcriptions`), {
+        method: "POST",
+        headers: { ...this.headers(correlationId), Accept: "application/json" },
+        body: form,
+        ...input.signal ? { signal: input.signal } : {}
+      });
+    } catch (error) {
+      if (input.signal?.aborted) throw error;
+      throw mutationTransportError(correlationId);
+    }
+    assertApiContractResponse(response);
+    if (!response.ok) throw await apiErrorFromResponse(response, { method: "POST", correlationId });
+    await assertJsonResponse(response, { method: "POST", correlationId });
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      throw new OpenGeniApiError(response.status, "Invalid transcription response.", {
+        code: "invalid_response",
+        mutation: true,
+        correlationId
+      });
+    }
+    if (!isTranscribeAudioResponse(body)) {
+      throw new OpenGeniApiError(response.status, "Invalid transcription response.", {
+        code: "invalid_response",
+        mutation: true,
+        correlationId
+      });
+    }
+    return body;
+  }
+  async createSession(workspaceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions`,
+      request
+    );
+  }
+  async getNewSessionDraft(workspaceId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/new-session-draft`
+    );
+  }
+  async saveNewSessionDraft(workspaceId, request) {
+    return await this.requestJson(
+      "PUT",
+      `/v1/workspaces/${workspaceId}/new-session-draft`,
+      request
+    );
+  }
+  async getSession(workspaceId, sessionId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}`
+    );
+  }
+  async updateSession(workspaceId, sessionId, request) {
+    return await this.requestJson(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}`,
+      request
+    );
+  }
+  /** Replace the durable tool policy or explicitly adopt workspace defaults. */
+  async updateSessionToolPolicy(workspaceId, sessionId, request) {
+    return await this.requestJson(
+      "PUT",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/tool-policy`,
+      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 = {}) {
+    if (options.search?.trim()) {
+      const page = await this.listSessionPage(workspaceId, options);
+      return [...page.pinned, ...page.sessions];
+    }
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions`,
+      void 0,
+      sessionListQuery(options)
+    );
+  }
+  /** Pin-aware ordinary-session page with a stable keyset cursor. */
+  async listSessionPage(workspaceId, options = {}) {
+    const search = options.search?.trim();
+    let response;
+    try {
+      response = await this.requestJson(
+        "GET",
+        `/v1/workspaces/${workspaceId}/sessions`,
+        void 0,
+        {
+          view: "page",
+          ...sessionListQuery(options),
+          ...options.cursor !== void 0 ? { 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, {
+          ...error.code ? { code: error.code } : {},
+          retryable: error.retryable,
+          ...error.correlationId ? { correlationId: error.correlationId } : {},
+          outcomeUnknown: error.outcomeUnknown,
+          displayMessage: "The session list changed \u2014 refresh and try again."
+        });
+      }
+      throw error;
+    }
+    if (Array.isArray(response)) {
+      if (options.cursor) {
+        throw new Error("The connected OpenGeni API does not support stable session-page cursors");
+      }
+      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. */
+  async updateSessionPin(workspaceId, sessionId, request) {
+    return await this.requestJson(
+      "PUT",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/pin`,
+      request
+    );
+  }
+  async getSessionLineage(workspaceId, sessionId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/lineage`
+    );
+  }
+  async listTurns(workspaceId, sessionId, options = {}) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/turns`,
+      void 0,
+      {
+        ...options.limit !== void 0 ? { limit: String(options.limit) } : {},
+        ...options.latestStarted ? { latestStarted: "1" } : {}
+      }
+    );
+  }
+  /** 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 });
+    return turns[0] ?? null;
+  }
+  // --- Bring-your-own-compute: Machines dashboard + metrics (M10) ------------
+  /**
+   * List the workspace's machines (the Machines dashboard). Each enrolled
+   * selfhosted machine carries its derived state + latest metrics +
+   * sharedSessionCount. Pass `sessionId` for an in-session view, which adds the
+   * session's synthetic Modal group box + the active-sandbox pointer.
+   */
+  async listMachines(workspaceId, options = {}) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/machines`,
+      void 0,
+      {
+        ...options.sessionId !== void 0 ? { sessionId: options.sessionId } : {}
+      },
+      { signal: options.signal }
+    );
+  }
+  /**
+   * Read the downsampled (~1/min) metrics series for ONE machine over a time
+   * window (default 1h). The samples are oldest-first (a left-to-right chart).
+   */
+  async machineMetricsSeries(workspaceId, enrollmentId, options = {}) {
+    const response = await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/machines/${enrollmentId}/metrics/series`,
+      void 0,
+      { ...options.window !== void 0 ? { window: options.window } : {} }
+    );
+    return response.samples;
+  }
+  // --- Self-hosted enrollment UX (design 11) --------------------------------
+  /**
+   * Resolve a pending device-enrollment flow by its user_code for the click-Grant
+   * approve page (EnrollmentConsent). NO workspace in the path — the server
+   * resolves the workspace from the (globally-unique-among-pending) code, then
+   * authorizes the caller against it (enrollments:read). Rejects (404) when the
+   * code is unknown/expired OR the caller lacks the grant — the two are
+   * indistinguishable by design (no cross-workspace disclosure). Does not consume
+   * the request.
+   */
+  async lookupDeviceEnrollment(userCode) {
+    return await this.requestJson(
+      "POST",
+      "/v1/enrollments/device/lookup",
+      { userCode }
+    );
+  }
+  /**
+   * Approve a pending device-enrollment flow (the LOUD consent step). `allowScreenControl`
+   * is the authoritative screen-control consent (whole-machine is mandatory/implicit).
+   * Lands an enrollment + a selfhosted sandbox and unblocks the agent's poll.
+   */
+  async approveDeviceEnrollment(workspaceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/enrollments/device/approve`,
+      { userCode: request.userCode, allowScreenControl: request.allowScreenControl ?? false }
+    );
+  }
+  /** Deny a pending device-enrollment flow (the explicit "no" at the approve page). */
+  async denyDeviceEnrollment(workspaceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/enrollments/device/deny`,
+      { userCode: request.userCode }
+    );
+  }
+  /**
+   * Mint a short-TTL headless enroll token (the `oget_` token) for the fleet /
+   * non-interactive enroll path. The returned `token` is SECRET — surface it once
+   * with a copy-now warning; it cannot be re-read. `allowScreenControl` bakes the
+   * screen-control consent into the token.
+   */
+  async mintEnrollToken(workspaceId, request = {}) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/enrollments/token`,
+      { allowScreenControl: request.allowScreenControl ?? false }
+    );
+  }
+  /**
+   * Swap a session's active sandbox (the user-authenticated equivalent of the
+   * M7 `sandbox_swap` MCP tool). `target` is a `MachineView.sandboxId` from
+   * `listMachines`, or "session"/"default" to swap back to the session's own
+   * group box. Validation (ownership/liveness/epoch fence) is server-side; the
+   * result echoes the resulting pointer (`swapped: false` + `reason` on a
+   * rejected target or a lost epoch fence).
+   */
+  async swapActiveSandbox(workspaceId, sessionId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/active-sandbox`,
+      request
+    );
+  }
+  // --- Scheduled tasks -------------------------------------------------------
+  async listScheduledTasks(workspaceId, options = {}) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/scheduled-tasks`,
+      void 0,
+      {
+        ...options.limit !== void 0 ? { limit: String(options.limit) } : {}
+      }
+    );
+  }
+  async getScheduledTask(workspaceId, taskId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}`
+    );
+  }
+  // --- Events: replay, send, stream ----------------------------------------
+  /**
+   * 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.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 correlationId = crypto.randomUUID();
+    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 } : {}
+      }),
+      {
+        method: "GET",
+        headers: { ...this.headers(correlationId), Accept: "application/json" }
+      }
+    );
+    assertApiContractResponse(response);
+    if (!response.ok) {
+      throw await apiErrorFromResponse(response, { method: "GET", correlationId });
+    }
+    await assertJsonResponse(response, { method: "GET", correlationId });
+    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) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/events`,
+      event
+    );
+  }
+  async sendMessage(workspaceId, sessionId, message) {
+    const input = typeof message === "string" ? { text: message } : message;
+    const { clientEventId, ...payload } = input;
+    return await this.sendEvent(workspaceId, sessionId, {
+      type: "user.message",
+      ...clientEventId !== void 0 ? { clientEventId } : {},
+      payload
+    });
+  }
+  async pauseSession(workspaceId, sessionId, options = {}) {
+    return await this.controlSession(workspaceId, sessionId, {
+      action: "pause",
+      clientEventId: options.clientEventId ?? crypto.randomUUID(),
+      ...options.reason ? { reason: options.reason } : {},
+      ...options.expectedControlEtag ? { expectedControlEtag: options.expectedControlEtag } : {}
+    });
+  }
+  async sendApprovalDecision(workspaceId, sessionId, decision) {
+    const { clientEventId, ...payload } = decision;
+    return await this.sendEvent(workspaceId, sessionId, {
+      type: "user.approvalDecision",
+      ...clientEventId !== void 0 ? { clientEventId } : {},
+      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
+   * {@link streamSessionEvents} for the delivery guarantees.
+   */
+  streamEvents(workspaceId, sessionId, options = {}) {
+    return streamSessionEvents(this.eventStreamTransport(workspaceId, sessionId), options);
+  }
+  /** The transport `streamEvents` runs on; useful for custom streaming layers. */
+  eventStreamTransport(workspaceId, sessionId) {
+    return {
+      openStream: async (after, signal) => await this.openEventStream(workspaceId, sessionId, {
+        after,
+        ...signal ? { signal } : {}
+      }),
+      listEvents: async (after, limit) => await this.listEvents(workspaceId, sessionId, { after, limit })
+    };
+  }
+  /** Open one raw SSE connection (no reconnect). Most callers want `streamEvents`. */
+  async openEventStream(workspaceId, sessionId, options = {}) {
+    const url = this.url(`/v1/workspaces/${workspaceId}/sessions/${sessionId}/events/stream`, {
+      after: String(options.after ?? 0)
+    });
+    const correlationId = crypto.randomUUID();
+    const response = await this.fetchImpl(url, {
+      method: "GET",
+      headers: { ...this.headers(correlationId), Accept: "text/event-stream" },
+      ...options.signal ? { signal: options.signal } : {}
+    });
+    assertApiContractResponse(response);
+    if (!response.ok) {
+      throw await apiErrorFromResponse(response, { method: "GET", correlationId });
+    }
+    if (!response.body) {
+      throw new OpenGeniApiError(response.status, "SSE response did not include a readable body");
+    }
+    return response.body;
+  }
+  // --- Turn queue ------------------------------------------------------------
+  async getQueue(workspaceId, sessionId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/queue`
+    );
+  }
+  async moveQueueItem(workspaceId, sessionId, turnId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/queue/${turnId}/move`,
+      request
+    );
+  }
+  async editQueueItem(workspaceId, sessionId, turnId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/queue/${turnId}/edit`,
+      request
+    );
+  }
+  async steerQueueItem(workspaceId, sessionId, turnId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/queue/${turnId}/steer`,
+      request
+    );
+  }
+  async deleteQueueItem(workspaceId, sessionId, turnId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/queue/${turnId}/delete`,
+      request
+    );
+  }
+  async getComposerDraft(workspaceId, sessionId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/composer-draft`
+    );
+  }
+  async saveComposerDraft(workspaceId, sessionId, request) {
+    return await this.requestJson(
+      "PUT",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/composer-draft`,
+      request
+    );
+  }
+  async controlSession(workspaceId, sessionId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/control`,
+      request
+    );
+  }
+  async resumeSession(workspaceId, sessionId, options = {}) {
+    return await this.controlSession(workspaceId, sessionId, {
+      action: "resume",
+      clientEventId: options.clientEventId ?? crypto.randomUUID(),
+      ...options.reason ? { reason: options.reason } : {},
+      ...options.expectedControlEtag ? { expectedControlEtag: options.expectedControlEtag } : {}
+    });
+  }
+  async setWorkspaceInferenceState(workspaceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/inference-control`,
+      request
+    );
+  }
+  async listWorkspaceControlEvents(workspaceId, options = {}) {
+    return (await this.listWorkspaceControlEventPage(workspaceId, options)).events;
+  }
+  /** Count/byte-bounded page plus an explicit continuation cursor. */
+  async listWorkspaceControlEventPage(workspaceId, options = {}) {
+    const correlationId = crypto.randomUUID();
+    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(correlationId), Accept: "application/json" }
+      }
+    );
+    assertApiContractResponse(response);
+    if (!response.ok) {
+      throw await apiErrorFromResponse(response, { method: "GET", correlationId });
+    }
+    await assertJsonResponse(response, { method: "GET", correlationId });
+    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);
+  }
+  workspaceControlStreamTransport(workspaceId) {
+    return {
+      openStream: async (after, signal) => await this.openWorkspaceControlEventStream(workspaceId, {
+        after,
+        ...signal ? { signal } : {}
+      })
+    };
+  }
+  async openWorkspaceControlEventStream(workspaceId, options = {}) {
+    const correlationId = crypto.randomUUID();
+    const response = await this.fetchImpl(
+      this.url(`/v1/workspaces/${workspaceId}/control-events/stream`, {
+        after: String(options.after ?? 0)
+      }),
+      {
+        method: "GET",
+        headers: { ...this.headers(correlationId), Accept: "text/event-stream" },
+        ...options.signal ? { signal: options.signal } : {}
+      }
+    );
+    assertApiContractResponse(response);
+    if (!response.ok) {
+      throw await apiErrorFromResponse(response, { method: "GET", correlationId });
+    }
+    if (!response.body) {
+      throw new OpenGeniApiError(response.status, "SSE response did not include a readable body");
+    }
+    return response.body;
+  }
+  /**
+   * Steer: atomically put this prompt at the head and supersede the current
+   * inference. The client performs one request and renders server order.
+   */
+  async steerMessage(workspaceId, sessionId, message) {
+    const input = typeof message === "string" ? { text: message } : message;
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/steer`,
+      input
+    );
+  }
+  // --- 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`
+    );
+  }
+  async updateGoal(workspaceId, sessionId, request) {
+    return await this.requestJson(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/goal`,
+      request
+    );
+  }
+  async deleteGoal(workspaceId, sessionId) {
+    await this.requestVoid("DELETE", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/goal`);
+  }
+  /** Pause the goal loop: the session stops self-continuing until resumed. */
+  async pauseGoal(workspaceId, sessionId, options = {}) {
+    return await this.updateGoal(workspaceId, sessionId, {
+      status: "paused",
+      ...options.rationale !== void 0 ? { rationale: options.rationale } : {}
+    });
+  }
+  /** Resume a paused goal: resets counters and re-arms the continuation loop. */
+  async resumeGoal(workspaceId, sessionId) {
+    return await this.updateGoal(workspaceId, sessionId, { status: "active" });
+  }
+  // --- Operator context controls (/clear, /compact) ---------------------------
+  /**
+   * Clear the session's conversation context. Destructive and audit-preserving:
+   * the server supersedes (never deletes) the live history and emits a
+   * `session.context.cleared` event. Refused (409) while a turn is in flight or
+   * awaiting action. `confirm:true` is sent so an accidental call cannot wipe
+   * context — the destructive intent is explicit on the wire.
+   */
+  async clearSessionContext(workspaceId, sessionId) {
+    await this.requestVoid(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/context/clear`,
+      { confirm: true }
+    );
+  }
+  /** Request one durable portable compaction at the next safe model boundary. */
+  async compactSessionContext(workspaceId, sessionId) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/context/compact`,
+      {}
+    );
+  }
+  // --- Channel-A structured services (P4.4) ------------------------------------
+  // FileSystem (Pierre tree), Git (Pierre diff), Terminal (exec + PTY). Each is a
+  // 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 = {}, options = {}) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/list`,
+      request,
+      {},
+      options
+    );
+  }
+  /** FileSystem: read a file (text or base64; binary-safe, size-capped). */
+  async fsRead(workspaceId, sessionId, request, options = {}) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/read`,
+      request,
+      {},
+      options
+    );
+  }
+  /** FileSystem: write a file (last-writer-wins; emits fs.changed). */
+  async fsWrite(workspaceId, sessionId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/write`,
+      request
+    );
+  }
+  /** FileSystem: delete a path (emits fs.changed). */
+  async fsDelete(workspaceId, sessionId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/delete`,
+      request
+    );
+  }
+  /** FileSystem: move/rename a path (emits fs.changed; 409 if destination exists and overwrite is false). */
+  async fsMove(workspaceId, sessionId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/move`,
+      request
+    );
+  }
+  /** FileSystem: create a directory (emits fs.changed; recursive defaults to true). */
+  async fsMkdir(workspaceId, sessionId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/mkdir`,
+      request
+    );
+  }
+  /** Git: working-tree/index status (the Pierre file-status feed). */
+  async gitStatus(workspaceId, sessionId, request = {}, options = {}) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/git/status`,
+      request,
+      {},
+      options
+    );
+  }
+  /** Git: structured diff hunks (the Pierre diff feed). */
+  async gitDiff(workspaceId, sessionId, request = {}, options = {}) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/git/diff`,
+      request,
+      {},
+      options
+    );
+  }
+  /** Git: commit log. */
+  async gitLog(workspaceId, sessionId, request = {}) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/git/log`,
+      request
+    );
+  }
+  /** Git: show a commit (diff vs first parent) or fetch a raw blob at a ref. */
+  async gitShow(workspaceId, sessionId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/git/show`,
+      request
+    );
+  }
+  /** Workspace capture: the latest turn-end snapshot of the session's workspace
+   *  (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, options = {}) {
+    return await this.requestJson(
+      "GET",
+      `/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, 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,
+      options
+    );
+  }
+  /** Terminal: run a bounded command, returning buffered stdout/stderr inline. */
+  async terminalExec(workspaceId, sessionId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/terminal/exec`,
+      request
+    );
+  }
+  /** Terminal: open an interactive PTY. Output streams on the event SSE as
+   *  terminal.pty.output.delta; drive it with terminalPtyWrite. */
+  async terminalPtyOpen(workspaceId, sessionId, request = {}) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/terminal/pty`,
+      request
+    );
+  }
+  /** Terminal: send stdin to an open PTY (output rides A1). */
+  async terminalPtyWrite(workspaceId, sessionId, request) {
+    await this.requestVoid(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/terminal/pty/write`,
+      request
+    );
+  }
+  /** Terminal: resize an open PTY. */
+  async terminalPtyResize(workspaceId, sessionId, request) {
+    await this.requestVoid(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/terminal/pty/resize`,
+      request
+    );
+  }
+  /** Terminal: close an open PTY (idempotent). */
+  async terminalPtyClose(workspaceId, sessionId, request) {
+    await this.requestVoid(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/terminal/pty/close`,
+      request
+    );
+  }
+  // --- Stream surfacing: capability negotiation + viewer lifecycle (Phase 5) ---
+  // The capability doc is the single source of UI truth (degradation is always a
+  // value, never a crash). The desktop pixel plane (Channel B) is gated behind an
+  // un-redacted-acknowledgment + a viewer holder; the structured terminal/files/
+  // git surfaces (Channel A) ride the methods above and the event SSE.
+  /** Read the negotiated capability doc for a session WITHOUT acquiring a viewer
+   *  holder (no warm, no spawn). Drives capability-gated rendering: which
+   *  surfaces mount, the per-surface unavailability reasons, and the lease
+   *  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, options = {}) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/stream-capabilities`,
+      void 0,
+      {},
+      options
+    );
+  }
+  /** Record the calling principal's acknowledgment of the un-redacted desktop
+   *  pixel plane (and, when the box is shared, the shared-exposure disclosure).
+   *  The desktop viewer-attach path returns 409 until this is recorded. */
+  async acknowledgeStream(workspaceId, sessionId, request = {}) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/stream-capabilities/acknowledge`,
+      request
+    );
+  }
+  /** Attach a viewer holder (refcounted liveness — keeps the box warm while
+   *  watched/used), spinning the box up in-process when cold, and mint the scoped
+   *  direct-to-provider URLs for the requested plane(s). `request.desktop:true`
+   *  opts into the un-redacted pixel plane and mints the noVNC URL — that plane
+   *  alone throws `OpenGeniApiError(409)` when the un-redacted/shared
+   *  acknowledgment is missing (the consent gate). A terminal-only attach
+   *  (`desktop` omitted/false) warms the box + mints the pty-ws terminal cell with
+   *  NO consent gate. An omitted `viewerId` mints a fresh one. */
+  async attachViewer(workspaceId, sessionId, request = {}) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/viewers`,
+      request
+    );
+  }
+  /** Heartbeat a viewer holder (Channel-A app-level liveness). A closed laptop
+   *  stops sending these → the reaper drops the holder within ~90s. Echoes
+   *  `leaseEpoch` so a superseded epoch is rejected (`alive:false` → re-attach). */
+  async heartbeatViewer(workspaceId, sessionId, viewerId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/viewers/${viewerId}/heartbeat`,
+      request
+    );
+  }
+  /** Detach a viewer (delete this holder; idempotent delete-my-row). */
+  async detachViewer(workspaceId, sessionId, viewerId) {
+    await this.requestVoid(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/viewers/${viewerId}`
+    );
+  }
+  // --- Access + workspaces -----------------------------------------------------
+  /**
+   * The deployment's public client bootstrap config: the host-exposed models
+   * (provider-grouped in `models`, flat in `allowedModels` for back-compat),
+   * reasoning efforts, MCP servers, file-upload limits, and how the client is
+   * expected to authenticate. Drives a composer's model picker without prior
+   * knowledge of the host setup; safe to call before any auth is established.
+   */
+  async getClientConfig() {
+    const config = await this.requestJson("GET", "/v1/config/client");
+    if (config.apiContractRevision !== OPENGENI_API_CONTRACT_REVISION) {
+      throw new OpenGeniApiContractMismatchError(
+        OPENGENI_API_CONTRACT_REVISION,
+        String(config.apiContractRevision || "(missing)")
+      );
+    }
+    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");
+  }
+  async listWorkspaces() {
+    return await this.requestJson("GET", "/v1/workspaces");
+  }
+  async createWorkspace(request) {
+    return await this.requestJson("POST", "/v1/workspaces", request);
+  }
+  async getWorkspace(workspaceId) {
+    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}`);
+  }
+  /** Read-time, secret-safe inventory of policy heads and visible workspace knowledge. */
+  async getWorkspaceState(workspaceId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/workspace-state`
+    );
+  }
+  async updateWorkspace(workspaceId, request) {
+    return await this.requestJson("PATCH", `/v1/workspaces/${workspaceId}`, request);
+  }
+  /** Inspect immutable instruction-policy history, active heads, and activation audit evidence. */
+  async listWorkspaceInstructionPolicies(workspaceId, options = {}) {
+    const params = new URLSearchParams();
+    if (options.kind !== void 0) params.set("kind", options.kind);
+    if (options.scope !== void 0) params.set("scope", options.scope);
+    if (options.roleKey !== void 0) params.set("roleKey", options.roleKey);
+    if (options.afterRevision !== void 0) {
+      params.set("afterRevision", String(options.afterRevision));
+    }
+    if (options.limit !== void 0) params.set("limit", String(options.limit));
+    const query = params.toString();
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/instruction-policies${query ? `?${query}` : ""}`
+    );
+  }
+  async getWorkspaceInstructionPolicyRevision(workspaceId, revisionId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/instruction-policies/${encodeURIComponent(revisionId)}`
+    );
+  }
+  async createWorkspaceInstructionPolicyDraft(workspaceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/instruction-policies/drafts`,
+      request
+    );
+  }
+  /** Import the stored legacy workspace override as an inactive charter draft. */
+  async importLegacyWorkspaceInstructionPolicyDraft(workspaceId, request = {}) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/instruction-policies/import-legacy`,
+      request
+    );
+  }
+  async diffWorkspaceInstructionPolicyRevisions(workspaceId, request) {
+    const params = new URLSearchParams({
+      fromRevisionId: request.fromRevisionId,
+      toRevisionId: request.toRevisionId
+    });
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/instruction-policies/diff?${params}`
+    );
+  }
+  async activateWorkspaceInstructionPolicyRevision(workspaceId, revisionId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/instruction-policies/${encodeURIComponent(revisionId)}/activate`,
+      request
+    );
+  }
+  async rollbackWorkspaceInstructionPolicyRevision(workspaceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/instruction-policies/rollback`,
+      request
+    );
+  }
+  async listPreferenceRegistry(workspaceId, options = {}) {
+    const params = new URLSearchParams();
+    if (options.scope) params.set("scope", options.scope);
+    if (options.status) params.set("status", options.status);
+    if (options.limit !== void 0) params.set("limit", String(options.limit));
+    const query = params.toString();
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/preferences${query ? `?${query}` : ""}`
+    );
+  }
+  async getPreferenceRegistry(workspaceId, preferenceId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}`
+    );
+  }
+  async createPreferenceRegistryProposal(workspaceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/proposals`,
+      request
+    );
+  }
+  async activatePreferenceRegistryRevision(workspaceId, preferenceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/activate`,
+      request
+    );
+  }
+  async correctPreferenceRegistry(workspaceId, preferenceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/correct`,
+      request
+    );
+  }
+  async changePreferenceRegistryScope(workspaceId, preferenceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/scope`,
+      request
+    );
+  }
+  async deactivatePreferenceRegistry(workspaceId, preferenceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/deactivate`,
+      request
+    );
+  }
+  async supersedePreferenceRegistry(workspaceId, preferenceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/supersede`,
+      request
+    );
+  }
+  async rejectPreferenceRegistryProposal(workspaceId, preferenceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/reject`,
+      request
+    );
+  }
+  async getPreferenceRegistrySummary(workspaceId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/preferences/summary`
+    );
+  }
+  async getPreferenceRegistryFullContent(workspaceId, retrievalHandle) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/full-content`,
+      { retrievalHandle }
+    );
+  }
+  /**
+   * Delete a workspace and everything in it. Refused (409) for the account's
+   * only workspace and while it still has a running session. Irreversible.
+   */
+  async deleteWorkspace(workspaceId) {
+    await this.requestVoid("DELETE", `/v1/workspaces/${workspaceId}`);
+  }
+  // --- Members ("People with access") -------------------------------------------
+  /** The workspace's members (user + api_key subjects). */
+  async listWorkspaceMembers(workspaceId) {
+    const response = await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/members`
+    );
+    return response.members;
+  }
+  /**
+   * Add an already-registered user by email. 404s when no user with that email
+   * exists (email invites for unknown users are deferred).
+   */
+  async addWorkspaceMember(workspaceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/members`,
+      request
+    );
+  }
+  async updateWorkspaceMember(workspaceId, subjectId, request) {
+    return await this.requestJson(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/members/${encodeURIComponent(subjectId)}`,
+      request
+    );
+  }
+  /**
+   * Remove a member. Refused (409) for your own membership and for the last
+   * member who can still manage the workspace.
+   */
+  async removeWorkspaceMember(workspaceId, subjectId) {
+    await this.requestVoid(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/members/${encodeURIComponent(subjectId)}`
+    );
+  }
+  // --- Scheduled tasks (write + runs) -------------------------------------------
+  async createScheduledTask(workspaceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/scheduled-tasks`,
+      request
+    );
+  }
+  async updateScheduledTask(workspaceId, taskId, request) {
+    return await this.requestJson(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}`,
+      request
+    );
+  }
+  async pauseScheduledTask(workspaceId, taskId) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}/pause`
+    );
+  }
+  async resumeScheduledTask(workspaceId, taskId) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}/resume`
+    );
+  }
+  /**
+   * Fire the task immediately (manual trigger), independent of its schedule.
+   * Pass a stable `triggerId` to make a retried trigger idempotent — the same
+   * token charges once and starts one run. Omit it and each call is distinct.
+   */
+  async triggerScheduledTask(workspaceId, taskId, options = {}) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}/trigger`,
+      options.triggerId ? { triggerId: options.triggerId } : void 0
+    );
+  }
+  async deleteScheduledTask(workspaceId, taskId) {
+    await this.requestJson(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}`
+    );
+  }
+  async listScheduledTaskRuns(workspaceId, taskId, options = {}) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}/runs`,
+      void 0,
+      { ...options.limit !== void 0 ? { limit: String(options.limit) } : {} }
+    );
+  }
+  // --- VariableSets --------------------------------------------------------------
+  // Variable values are write-only: reads return name/version metadata only.
+  async listVariableSets(workspaceId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/variable-sets`
+    );
+  }
+  async createVariableSet(workspaceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/variable-sets`,
+      request
+    );
+  }
+  async getVariableSet(workspaceId, variableSetId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/variable-sets/${variableSetId}`
+    );
+  }
+  async updateVariableSet(workspaceId, variableSetId, request) {
+    return await this.requestJson(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/variable-sets/${variableSetId}`,
+      request
+    );
+  }
+  async deleteVariableSet(workspaceId, variableSetId) {
+    await this.requestJson(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/variable-sets/${variableSetId}`
+    );
+  }
+  /** Create or rotate a variable. The value never comes back on any read. */
+  async setVariableSetVariable(workspaceId, variableSetId, name, value) {
+    return await this.requestJson(
+      "PUT",
+      `/v1/workspaces/${workspaceId}/variable-sets/${variableSetId}/variables/${encodeURIComponent(name)}`,
+      { value }
+    );
+  }
+  async deleteVariableSetVariable(workspaceId, variableSetId, name) {
+    await this.requestJson(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/variable-sets/${variableSetId}/variables/${encodeURIComponent(name)}`
+    );
+  }
+  // --- Rigs ------------------------------------------------------------------
+  // Workspace-scoped, versioned sandbox machine definitions. rigs:use gates read
+  // + proposeRigChange; rigs:manage gates create / update / delete / activate.
+  async listRigs(workspaceId) {
+    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/rigs`);
+  }
+  async createRig(workspaceId, request) {
+    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/rigs`, request);
+  }
+  async getRig(workspaceId, rigId) {
+    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/rigs/${rigId}`);
+  }
+  async updateRig(workspaceId, rigId, request) {
+    return await this.requestJson(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/rigs/${rigId}`,
+      request
+    );
+  }
+  async deleteRig(workspaceId, rigId) {
+    await this.requestJson("DELETE", `/v1/workspaces/${workspaceId}/rigs/${rigId}`);
+  }
+  async listRigVersions(workspaceId, rigId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/rigs/${rigId}/versions`
+    );
+  }
+  /** Roll the active version to an existing one (rollback / promote-activate). */
+  async activateRigVersion(workspaceId, rigId, versionId) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/rigs/${rigId}/versions/${versionId}/activate`
+    );
+  }
+  async listRigChanges(workspaceId, rigId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/rigs/${rigId}/changes`
+    );
+  }
+  /** Propose a change against the rig's active version (rigs:use). */
+  async proposeRigChange(workspaceId, rigId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/rigs/${rigId}/changes`,
+      request
+    );
+  }
+  async getRigChange(workspaceId, rigId, changeId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/rigs/${rigId}/changes/${changeId}`
+    );
+  }
+  /**
+   * Re-run verification for a change (rigs:use). Verification is asynchronous:
+   * this returns the change immediately with status `verifying`; poll
+   * `getRigChange`/`listRigChanges` for the terminal outcome + logs.
+   */
+  async verifyRigChange(workspaceId, rigId, changeId) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/rigs/${rigId}/changes/${changeId}/verify`
+    );
+  }
+  /**
+   * Promote a verified `definition_edit` change into a new active rig version
+   * (rigs:manage). Only valid once the change's verification passed; returns the
+   * newly minted version.
+   */
+  async promoteRigChange(workspaceId, rigId, changeId) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/rigs/${rigId}/changes/${changeId}/promote`
+    );
+  }
+  /**
+   * Re-run the active version's checks in a clean throwaway sandbox (rigs:use).
+   * Asynchronous — returns the version id being verified; the outcome lands on
+   * the version's audit trail.
+   */
+  async verifyRig(workspaceId, rigId) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/rigs/${rigId}/verify`
+    );
+  }
+  /** @deprecated use listVariableSets */
+  async listEnvironments(workspaceId) {
+    return await this.listVariableSets(workspaceId);
+  }
+  /** @deprecated use createVariableSet */
+  async createEnvironment(workspaceId, request) {
+    return await this.createVariableSet(workspaceId, request);
+  }
+  /** @deprecated use getVariableSet */
+  async getEnvironment(workspaceId, environmentId) {
+    return await this.getVariableSet(workspaceId, environmentId);
+  }
+  /** @deprecated use updateVariableSet */
+  async updateEnvironment(workspaceId, environmentId, request) {
+    return await this.updateVariableSet(workspaceId, environmentId, request);
+  }
+  /** @deprecated use deleteVariableSet */
+  async deleteEnvironment(workspaceId, environmentId) {
+    await this.deleteVariableSet(workspaceId, environmentId);
+  }
+  /** @deprecated use setVariableSetVariable */
+  async setEnvironmentVariable(workspaceId, environmentId, name, value) {
+    return await this.setVariableSetVariable(workspaceId, environmentId, name, value);
+  }
+  /** @deprecated use deleteVariableSetVariable */
+  async deleteEnvironmentVariable(workspaceId, environmentId, name) {
+    await this.deleteVariableSetVariable(workspaceId, environmentId, name);
+  }
+  // --- Files -----------------------------------------------------------------------
+  /** Step 1 of the upload flow: returns the pre-signed PUT target. */
+  async beginFileUpload(workspaceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/files/uploads`,
+      request
+    );
+  }
+  /** Step 3 of the upload flow: server verifies the object and marks it ready. */
+  async completeFileUpload(workspaceId, uploadId) {
+    const response = await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/files/uploads/${uploadId}/complete`
+    );
+    return response.file;
+  }
+  /**
+   * The whole upload flow as one call: begin -> PUT the bytes to the signed
+   * URL (with its required headers; no API auth is sent to object storage)
+   * -> complete. Returns the ready `FileAsset`.
+   */
+  async uploadFile(workspaceId, input) {
+    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",
+      // 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
+    });
+    if (!putResponse.ok) {
+      throw await apiErrorFromResponse(putResponse, { method: "PUT" });
+    }
+    return await this.completeFileUpload(workspaceId, upload.uploadId);
+  }
+  async getFile(workspaceId, fileId) {
+    return await this.requestJson(
+      "GET",
+      `/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 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 } : {}
+      }
+    );
+    try {
+      assertApiContractResponse(response);
+    } catch (error) {
+      await cancelResponseBody(response, "retained artifact API contract mismatch");
+      throw error;
+    }
+    if (!response.ok) {
+      throw await apiErrorFromResponse(response, { method: "GET", correlationId });
+    }
+    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(
+      "POST",
+      `/v1/workspaces/${workspaceId}/files/${fileId}/download-url`
+    );
+  }
+  // --- Documents ----------------------------------------------------------------------
+  async createDocumentBase(workspaceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/document-bases`,
+      request
+    );
+  }
+  async listDocumentBases(workspaceId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/document-bases`
+    );
+  }
+  async getDocumentBase(workspaceId, baseId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/document-bases/${baseId}`
+    );
+  }
+  /** Index an uploaded file into the base. The file must be `ready`. */
+  async addDocument(workspaceId, baseId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/document-bases/${baseId}/documents`,
+      request
+    );
+  }
+  async listDocuments(workspaceId, baseId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/document-bases/${baseId}/documents`
+    );
+  }
+  /**
+   * Drop raw text or an already-uploaded file into the workspace's Default
+   * base. When curation is enabled, it may name, summarize, categorize, and
+   * (confidence permitting) file the document into the best-matching base;
+   * provider=none leaves caller metadata and Default placement unchanged.
+   */
+  async createKnowledgeDrop(workspaceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/knowledge/drops`,
+      request
+    );
+  }
+  /**
+   * Move a document (and its indexed chunks) to another base. With no
+   * targetBaseId, applies the document's stored curation suggestion.
+   */
+  async moveDocument(workspaceId, documentId, request = {}) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/documents/${documentId}/move`,
+      request
+    );
+  }
+  /** Retry indexing for a failed document. */
+  async reindexDocument(workspaceId, baseId, documentId) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/document-bases/${baseId}/documents/${documentId}/reindex`
+    );
+  }
+  /**
+   * Delete a document from a base. Removes the document row and its indexed
+   * chunks while leaving the uploaded file asset available for other uses.
+   */
+  async deleteDocument(workspaceId, baseId, documentId) {
+    await this.requestVoid(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/document-bases/${baseId}/documents/${documentId}`
+    );
+  }
+  async searchDocuments(workspaceId, baseId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/document-bases/${baseId}/search`,
+      request
+    );
+  }
+  async searchKnowledge(workspaceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/knowledge/search`,
+      request
+    );
+  }
+  async listKnowledgeMemories(workspaceId, request = {}) {
+    const params = new URLSearchParams();
+    if (request.query) params.set("query", request.query);
+    if (request.status) params.set("status", request.status);
+    if (request.kind) params.set("kind", request.kind);
+    if (request.scope) params.set("scope", request.scope);
+    if (request.limit) params.set("limit", String(request.limit));
+    const query = params.toString();
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/knowledge/memories${query ? `?${query}` : ""}`
+    );
+  }
+  async getKnowledgeMemory(workspaceId, memoryId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/knowledge/memories/${memoryId}`
+    );
+  }
+  async createKnowledgeMemory(workspaceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/knowledge/memories`,
+      request
+    );
+  }
+  async updateKnowledgeMemory(workspaceId, memoryId, request) {
+    return await this.requestJson(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/knowledge/memories/${memoryId}`,
+      request
+    );
+  }
+  /** Hybrid (semantic + keyword) search over the workspace's agent-visible memory. */
+  async searchWorkspaceMemories(workspaceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/knowledge/memories/search`,
+      request
+    );
+  }
+  /** Deep-merge a settings patch into the workspace (preserves unknown keys). */
+  async updateWorkspaceSettings(workspaceId, request) {
+    return await this.requestJson(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/settings`,
+      request
+    );
+  }
+  async setWorkspaceDefaultRig(workspaceId, request) {
+    return await this.requestJson(
+      "PUT",
+      `/v1/workspaces/${workspaceId}/default-rig`,
+      request
+    );
+  }
+  // --- Capability packs ------------------------------------------------------------------
+  /** Built-in + registered packs, with the workspace's installations. */
+  async listPacks(workspaceId) {
+    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/packs`);
+  }
+  /** Register (or replace) a workspace-scoped pack from a manifest. */
+  async registerPack(workspaceId, manifest) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/packs`,
+      manifest
+    );
+  }
+  async getPack(workspaceId, packId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/packs/${encodeURIComponent(packId)}`
+    );
+  }
+  async enablePack(workspaceId, packId, request = {}) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/packs/${encodeURIComponent(packId)}/enable`,
+      request
+    );
+  }
+  /** Unregister a workspace-scoped pack (built-in packs cannot be deleted). */
+  async deletePack(workspaceId, packId) {
+    await this.requestVoid(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/packs/${encodeURIComponent(packId)}`
+    );
+  }
+  async listPackInstallations(workspaceId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/packs/installations`
+    );
+  }
+  // --- Capabilities -------------------------------------------------------------------------
+  async listCapabilities(workspaceId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/capabilities`
+    );
+  }
+  /** Add a manual capability catalog item (e.g. a remote MCP server). */
+  async createCapability(workspaceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/capabilities`,
+      request
+    );
+  }
+  async enableCapability(workspaceId, capabilityId, request = {}) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/capabilities/${encodeURIComponent(capabilityId)}/enable`,
+      request
+    );
+  }
+  async disableCapability(workspaceId, capabilityId) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/capabilities/${encodeURIComponent(capabilityId)}/disable`
+    );
+  }
+  /** Search the official MCP registry for installable capabilities. */
+  async discoverMcpCapabilities(workspaceId, options = {}) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/capabilities/discovery/mcp-registry`,
+      void 0,
+      {
+        ...options.query !== void 0 ? { query: options.query } : {},
+        ...options.limit !== void 0 ? { limit: String(options.limit) } : {}
+      }
+    );
+  }
+  // --- Connections -------------------------------------------------------------------------------
+  async listConnections(workspaceId) {
+    const response = await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/connections`
+    );
+    return response.connections;
+  }
+  async createConnection(workspaceId, request) {
+    const response = await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/connections`,
+      request
+    );
+    return response.connection;
+  }
+  /** Start the public Slack installation flow for the workspace-shared OpenGeni bot. */
+  async startOpenGeniSlackBotInstall(workspaceId, request = {}) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/connections/slack-bot/install`,
+      request
+    );
+  }
+  async updateConnection(workspaceId, connectionId, request) {
+    const response = await this.requestJson(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/connections/${connectionId}`,
+      request
+    );
+    return response.connection;
+  }
+  async deleteConnection(workspaceId, connectionId) {
+    const response = await this.requestJson(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/connections/${connectionId}`
+    );
+    return response.connection;
+  }
+  /** Start an OAuth connection flow; redirect the user to the returned `authorizationUrl`. */
+  async startConnectionOAuth(workspaceId, request, options = {}) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/connections/oauth/start`,
+      request,
+      {},
+      options
+    );
+  }
+  /** Public, immutably-cached URL for a catalog item's logo, or null when the item has none. */
+  catalogAssetUrl(logoAssetPath) {
+    return logoAssetPath ? `${this.baseUrl}/v1/${logoAssetPath}` : null;
+  }
+  // --- GitHub ----------------------------------------------------------------------------------
+  /** GitHub App server configuration plus truthful workspace binding status. */
+  async getGitHubApp(workspaceId) {
+    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/github/app`);
+  }
+  /** Build the GitHub owner-consent entry URL for fresh workspace-bound state. */
+  githubConnectUrl(workspaceId, state) {
+    return this.url(`/v1/workspaces/${workspaceId}/github/connect`, { state });
+  }
+  async listGitHubRepositories(workspaceId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/github/repositories`
+    );
+  }
+  /** Re-sync the installation's repository list from GitHub. */
+  async syncGitHubRepositories(workspaceId) {
+    return await this.requestJson(
+      "POST",
+      `/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(
+      "POST",
+      `/v1/workspaces/${workspaceId}/github/app-manifest`,
+      request
+    );
+  }
+  // --- API keys ----------------------------------------------------------------------------------
+  async listApiKeys(workspaceId) {
+    const response = await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/api-keys`
+    );
+    return response.apiKeys;
+  }
+  /** The returned `token` is shown once; only its prefix is stored. */
+  async createApiKey(workspaceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/api-keys`,
+      request
+    );
+  }
+  /** Revoke an API key. Returns the revoked key. */
+  async deleteApiKey(workspaceId, apiKeyId) {
+    return await this.requestJson(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/api-keys/${apiKeyId}`
+    );
+  }
+  // --- Billing (account-scoped) --------------------------------------------------------------------
+  async getBilling(options = {}) {
+    return await this.requestJson("GET", "/v1/billing", void 0, {
+      ...options.accountId !== void 0 ? { accountId: options.accountId } : {}
+    });
+  }
+  async getBillingUsage(options = {}) {
+    return await this.requestJson("GET", "/v1/billing/usage", void 0, {
+      ...options.accountId !== void 0 ? { accountId: options.accountId } : {},
+      ...options.workspaceId !== void 0 ? { workspaceId: options.workspaceId } : {}
+    });
+  }
+  async getWorkspaceInsights(workspaceId, options = {}) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/insights`,
+      void 0,
+      {
+        range: options.range ?? "week",
+        ...options.provider !== void 0 ? { provider: options.provider } : {},
+        ...options.model !== void 0 ? { model: options.model } : {}
+      }
+    );
+  }
+  async getBillingEntitlements(options = {}) {
+    return await this.requestJson(
+      "GET",
+      "/v1/billing/entitlements",
+      void 0,
+      {
+        ...options.accountId !== void 0 ? { accountId: options.accountId } : {}
+      }
+    );
+  }
+  /** Start a Stripe checkout for prepaid credits. */
+  async createBillingCheckout(request) {
+    return await this.requestJson("POST", "/v1/billing/checkout", request);
+  }
+  // --- Internals -------------------------------------------------------------
+  headers(correlationId) {
+    const extra = typeof this.options.headers === "function" ? this.options.headers() : this.options.headers;
+    return {
+      ...this.options.apiKey ? { Authorization: `Bearer ${this.options.apiKey}` } : {},
+      ...extra,
+      [OPENGENI_API_CONTRACT_HEADER]: OPENGENI_API_CONTRACT_REVISION,
+      ...correlationId ? { [OPENGENI_CORRELATION_HEADER]: correlationId } : {}
+    };
+  }
+  url(path, query = {}) {
+    const params = new URLSearchParams(query).toString();
+    return `${this.baseUrl}${path}${params ? `?${params}` : ""}`;
+  }
+  // --- Codex (ChatGPT) subscription (workspace-scoped) --------------------------------------------
+  /** Connection state + the codex models the workspace may select (empty until connected). */
+  async codexStatus(workspaceId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/codex/status`
+    );
+  }
+  /** Begin device-code login: show `userCode` at `verificationUri`, then poll with `state`. */
+  async codexConnectStart(workspaceId) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/codex/connect/start`
+    );
+  }
+  /** Poll device-code authorization with the `state` from {@link codexConnectStart}. */
+  async codexConnectPoll(workspaceId, state) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/codex/connect/poll`,
+      { state }
+    );
+  }
+  /** Remaining usage / limits for the connected (ACTIVE) subscription. Back-compat. */
+  async codexUsage(workspaceId) {
+    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/codex/usage`);
+  }
+  /** Live per-account usage read (refreshes THIS account's bearer; writes the cache). */
+  async codexAccountUsage(workspaceId, accountId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/codex/accounts/${accountId}/usage`
+    );
+  }
+  /** Batched live refresh across every connected account, keyed by credential id. */
+  async refreshCodexUsage(workspaceId) {
+    return await this.requestJson(
+      "POST",
+      `/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(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/codex`
+    );
+  }
+  /** List every connected Codex account + the workspace active pointer + settings. */
+  async listCodexAccounts(workspaceId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/codex/accounts`
+    );
+  }
+  /** Switch the workspace ACTIVE Codex account (the one unpinned sessions use). */
+  async activateCodexAccount(workspaceId, accountId) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/codex/accounts/${accountId}/activate`
+    );
+  }
+  /** P3: enable/disable Codex auto-rotation and/or pick the strategy. Returns the effective settings. */
+  async setCodexRotationSettings(workspaceId, patch) {
+    return await this.requestJson(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/codex/settings`,
+      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(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/codex/accounts/${accountId}`
+    );
+  }
+  /** Rename a Codex account (label only in P1). */
+  async renameCodexAccount(workspaceId, accountId, label) {
+    return await this.requestJson(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/codex/accounts/${accountId}`,
+      { label }
+    );
+  }
+  /** Pin (or unpin via "auto") a session's Codex account. Applies on the next turn. */
+  async pinSessionCodexAccount(workspaceId, sessionId, target) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/codex-account`,
+      { target }
+    );
+  }
+  async requestJson(method, path, body, query = {}, options = {}) {
+    const correlationId = crypto.randomUUID();
+    let response;
+    try {
+      response = await this.fetchImpl(this.url(path, query), {
+        method,
+        headers: {
+          ...this.headers(correlationId),
+          Accept: "application/json",
+          ...body !== void 0 ? { "Content-Type": "application/json" } : {}
+        },
+        ...body !== void 0 ? { body: JSON.stringify(body) } : {},
+        ...options.signal ? { signal: options.signal } : {}
+      });
+    } catch (error) {
+      if (isMutationMethod(method)) {
+        throw mutationTransportError(correlationId);
+      }
+      throw error;
+    }
+    assertApiContractResponse(response);
+    if (!response.ok) {
+      throw await apiErrorFromResponse(response, { method, correlationId });
+    }
+    await assertJsonResponse(response, { method, correlationId });
+    try {
+      return await response.json();
+    } catch (error) {
+      if (isMutationMethod(method)) {
+        throw mutationTransportError(correlationId);
+      }
+      throw error;
+    }
+  }
+  /** Like `requestJson` for endpoints that respond with no body (204). */
+  async requestVoid(method, path, body) {
+    const correlationId = crypto.randomUUID();
+    let response;
+    try {
+      response = await this.fetchImpl(this.url(path), {
+        method,
+        headers: {
+          ...this.headers(correlationId),
+          Accept: "application/json",
+          ...body !== void 0 ? { "Content-Type": "application/json" } : {}
+        },
+        ...body !== void 0 ? { body: JSON.stringify(body) } : {}
+      });
+    } catch (error) {
+      if (isMutationMethod(method)) {
+        throw mutationTransportError(correlationId);
+      }
+      throw error;
+    }
+    assertApiContractResponse(response);
+    if (!response.ok) {
+      throw await apiErrorFromResponse(response, { method, correlationId });
+    }
+  }
+};
+function assertApiContractResponse(response) {
+  const actual = response.headers.get(OPENGENI_API_CONTRACT_HEADER);
+  if (actual && actual !== OPENGENI_API_CONTRACT_REVISION) {
+    throw new OpenGeniApiContractMismatchError(OPENGENI_API_CONTRACT_REVISION, actual);
+  }
+}
+function isTranscribeAudioResponse(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = value;
+  return typeof record.text === "string" && Array.isArray(record.languages) && record.languages.every((language) => typeof language === "string");
+}
+function filenameForAudioMimeType(mimeType) {
+  const bare = mimeType.trim().toLowerCase().split(";")[0] ?? "audio/webm";
+  switch (bare) {
+    case "audio/mp4":
+    case "audio/m4a":
+      return "audio.mp4";
+    case "audio/ogg":
+      return "audio.ogg";
+    case "audio/mpeg":
+    case "audio/mp3":
+      return "audio.mp3";
+    case "audio/wav":
+    case "audio/x-wav":
+      return "audio.wav";
+    case "audio/webm":
+    default:
+      return "audio.webm";
+  }
+}
+var API_ERROR_MAX_BYTES = 16 * 1024;
+async function apiErrorFromResponse(response, context) {
+  return new OpenGeniApiError(response.status, await readBoundedJsonErrorBody(response), {
+    correlationId: response.headers.get(OPENGENI_CORRELATION_HEADER) ?? context.correlationId,
+    mutation: isMutationMethod(context.method)
+  });
+}
+async function assertJsonResponse(response, context) {
+  if (isJsonContentType(response.headers.get("content-type"))) return;
+  await cancelResponseBody(response, "unexpected non-JSON API response");
+  throw new OpenGeniApiError(502, "", {
+    code: "upstream_unavailable",
+    retryable: true,
+    correlationId: response.headers.get(OPENGENI_CORRELATION_HEADER) ?? context.correlationId,
+    outcomeUnknown: isMutationMethod(context.method),
+    displayMessage: "OpenGeni is temporarily unavailable \u2014 retry."
+  });
+}
+async function readBoundedJsonErrorBody(response) {
+  if (!isJsonContentType(response.headers.get("content-type"))) {
+    await cancelResponseBody(response, "discarding API error body");
+    return "";
+  }
+  if (Number(response.headers.get("content-length")) > API_ERROR_MAX_BYTES) {
+    await cancelResponseBody(response, "discarding API error body");
+    return "";
+  }
+  try {
+    return new TextDecoder().decode(
+      await readBoundedResponseBytes(response, API_ERROR_MAX_BYTES, null)
+    );
+  } catch {
+    return "";
+  }
+}
+function isJsonContentType(value) {
+  return /^(application\/json|[^;]+\+json)\s*(;|$)/i.test(value ?? "");
+}
+function isMutationMethod(method) {
+  return method !== "GET" && method !== "HEAD" && method !== "OPTIONS";
+}
+function mutationTransportError(correlationId) {
+  return new OpenGeniApiError(0, "", {
+    code: "network_error",
+    retryable: true,
+    correlationId,
+    outcomeUnknown: true,
+    mutation: true,
+    displayMessage: "OpenGeni could not confirm the request \u2014 reconcile before retrying."
+  });
+}
+async function sha256ForUpload(body) {
+  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 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/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 resolveWorkspaceVoiceInputEnabled(settings) {
+  if (!isRecord(settings)) return null;
+  const voiceInput = settings.voiceInput;
+  if (isRecord(voiceInput) && typeof voiceInput.enabled === "boolean") {
+    return voiceInput.enabled;
+  }
+  const legacy = settings.transcription;
+  return isRecord(legacy) && typeof legacy.enabled === "boolean" ? legacy.enabled : 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 {
+  OpenGeniApiError,
+  OpenGeniSessionListCursorError,
+  OpenGeniApiContractMismatchError,
+  OpenGeniStreamError,
+  isRetryableStreamError,
+  parseSseStream,
+  streamSessionEvents,
+  streamWorkspaceControlEvents,
+  SESSION_EVENT_TYPES,
+  KNOWN_PERMISSIONS,
+  OPENGENI_API_CONTRACT_REVISION,
+  OPENGENI_API_CONTRACT_HEADER,
+  OPENGENI_CORRELATION_HEADER,
+  RETAINED_OUTPUT_DEFAULT_PAGE_BYTES,
+  RETAINED_OUTPUT_MAX_PAGE_BYTES,
+  KNOWN_USAGE_EVENT_TYPES,
+  OpenGeniClient,
+  DEFAULT_WORKSPACE_TRANSCRIPTION_POLICY,
+  resolveWorkspaceVoiceInputEnabled,
+  resolveWorkspaceTranscriptionPolicy,
+  authorizeTranscriptionAdapter,
+  createTranscriptionSessionRequest
+};
+//# sourceMappingURL=chunk-YROWFD7R.js.map