@opengeni/sdk 0.13.0 → 0.20.0

package/dist/index.js

@@ -9,6 +9,16 @@ var OpenGeniApiError = class extends Error {
     this.body = body;
   }
 };
+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);
@@ -114,6 +124,7 @@ async function* streamSessionEvents(transport, options = {}) {
       everConnected = true;
       failedAttempts = 0;
       delayMs = baseDelayMs;
+      await options.beforeLive?.();
       options.onStateChange?.("live");
       for await (const message of parseSseStream(body)) {
         if (signal?.aborted) {
@@ -208,6 +219,251 @@ async function sleep(delayMs, signal) {
   });
 }
 
+// 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.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.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",
+  "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",
+  // 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",
+  // 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"
+];
+var OPENGENI_API_CONTRACT_REVISION = "2026-07-turn-instructions-v1";
+var OPENGENI_API_CONTRACT_HEADER = "x-opengeni-api-contract";
+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
 var OpenGeniClient = class {
   baseUrl;
@@ -255,7 +511,7 @@ var OpenGeniClient = class {
   }
   /** Pin-aware ordinary-session page with a stable keyset cursor. */
   async listSessionPage(workspaceId, options = {}) {
-    const response = await this.requestJson(
+    return await this.requestJson(
       "GET",
       `/v1/workspaces/${workspaceId}/sessions`,
       void 0,
@@ -269,16 +525,6 @@ var OpenGeniClient = class {
         } : {}
       }
     );
-    if (Array.isArray(response)) {
-      if (options.cursor) {
-        throw new Error("The connected OpenGeni API does not support stable session-page cursors");
-      }
-      if (options.search?.trim()) {
-        throw new Error("The connected OpenGeni API does not support session search");
-      }
-      return { pinned: [], sessions: response, nextCursor: null };
-    }
-    return response;
   }
   /** Set this authenticated member's personal workspace pin for a session. */
   async updateSessionPin(workspaceId, sessionId, request) {
@@ -318,7 +564,8 @@ var OpenGeniClient = class {
       void 0,
       {
         ...options.sessionId !== void 0 ? { sessionId: options.sessionId } : {}
-      }
+      },
+      { signal: options.signal }
     );
   }
   /**
@@ -418,23 +665,75 @@ var OpenGeniClient = class {
   }
   // --- Events: replay, send, stream ----------------------------------------
   /**
-   * Replay durable events by sequence, ascending. `before` is exclusive and
-   * returns the newest matching window. With `compact`, consecutive delta runs
-   * may be coalesced; `payload.coalescedUntil` carries the run's last sequence
-   * for resume cursors.
+   * Return the events from one bounded page. With no cursor, this uses the safe
+   * semantic monitoring tail; pass explicit forensic options and a cursor for
+   * retained audit replay. Use `listEventPage` when projection, coverage, or
+   * resume-cursor facts are required.
    */
   async listEvents(workspaceId, sessionId, options = {}) {
-    return await this.requestJson(
-      "GET",
-      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/events`,
-      void 0,
-      {
+    return (await this.listEventPage(workspaceId, sessionId, options)).events;
+  }
+  /** Bounded durable/monitoring page plus exact projection and cursor facts. */
+  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");
+    }
+    const response = await this.fetchImpl(
+      this.url(`/v1/workspaces/${workspaceId}/sessions/${sessionId}/events`, {
         ...options.after !== void 0 ? { after: String(options.after) } : {},
         ...options.before !== void 0 ? { before: String(options.before) } : {},
         ...options.limit !== void 0 ? { limit: String(options.limit) } : {},
-        ...options.compact ? { compact: "1" } : {}
+        ...options.compact ? { compact: "1" } : {},
+        ...options.mode ? { mode: options.mode } : {},
+        ...options.direction ? { direction: options.direction } : {},
+        ...options.payloadMode ? { payloadMode: options.payloadMode } : {},
+        ...options.includeTypes?.length ? { includeTypes: options.includeTypes.join(",") } : {},
+        ...options.excludeTypes?.length ? { excludeTypes: options.excludeTypes.join(",") } : {},
+        ...options.includeClasses?.length ? { includeClasses: options.includeClasses.join(",") } : {},
+        ...options.excludeClasses?.length ? { excludeClasses: options.excludeClasses.join(",") } : {},
+        ...options.latest ? { latest: options.latest } : {}
+      }),
+      {
+        method: "GET",
+        headers: { ...this.headers(), Accept: "application/json" }
       }
     );
+    assertApiContractResponse(response);
+    if (!response.ok) throw new OpenGeniApiError(response.status, await safeText(response));
+    const events = await response.json();
+    const 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"
+    };
   }
   /** POST a user/control event to the session. Returns the accepted event. */
   async sendEvent(workspaceId, sessionId, event) {
@@ -454,10 +753,12 @@ var OpenGeniClient = class {
     });
   }
   async pauseSession(workspaceId, sessionId, options = {}) {
-    return (await this.controlSession(workspaceId, sessionId, {
-      mode: "pause",
-      ...options
-    })).event;
+    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;
@@ -467,6 +768,28 @@ var OpenGeniClient = class {
       payload
     });
   }
+  async listHumanInputRequests(workspaceId, sessionId, options = {}) {
+    const result = await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/human-input-requests`,
+      void 0,
+      options.status ? { status: options.status } : void 0
+    );
+    return result.requests;
+  }
+  async getHumanInputRequest(workspaceId, sessionId, requestId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/human-input-requests/${requestId}`
+    );
+  }
+  async submitHumanInputResponse(workspaceId, sessionId, requestId, response, options = {}) {
+    return await this.sendEvent(workspaceId, sessionId, {
+      type: "user.humanInputResponse",
+      ...options.clientEventId ? { clientEventId: options.clientEventId } : {},
+      payload: { requestId, response }
+    });
+  }
   /**
    * Live-stream a session's events with automatic reconnect, resume from the
    * last seen sequence, gap backfill, and duplicate suppression. See
@@ -495,6 +818,7 @@ var OpenGeniClient = class {
       headers: { ...this.headers(), Accept: "text/event-stream" },
       ...options.signal ? { signal: options.signal } : {}
     });
+    assertApiContractResponse(response);
     if (!response.ok) {
       throw new OpenGeniApiError(response.status, await safeText(response));
     }
@@ -510,10 +834,44 @@ var OpenGeniClient = class {
       `/v1/workspaces/${workspaceId}/sessions/${sessionId}/queue`
     );
   }
-  async cancelQueueItem(workspaceId, sessionId, turnId, request) {
+  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}/cancel`,
+      `/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
     );
   }
@@ -525,7 +883,12 @@ var OpenGeniClient = class {
     );
   }
   async resumeSession(workspaceId, sessionId, options = {}) {
-    return await this.controlSession(workspaceId, sessionId, { mode: "resume", ...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(
@@ -534,12 +897,65 @@ var OpenGeniClient = class {
       request
     );
   }
-  /** Cancel a queued turn before it is claimed. Returns the cancelled turn. */
-  async deleteQueuedTurn(workspaceId, sessionId, turnId) {
-    return await this.requestJson(
-      "DELETE",
-      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/turns/${turnId}`
+  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 response = await this.fetchImpl(
+      this.url(`/v1/workspaces/${workspaceId}/control-events`, {
+        ...options.after !== void 0 ? { after: String(options.after) } : {},
+        ...options.limit !== void 0 ? { limit: String(options.limit) } : {}
+      }),
+      {
+        method: "GET",
+        headers: { ...this.headers(), Accept: "application/json" }
+      }
     );
+    assertApiContractResponse(response);
+    if (!response.ok) {
+      throw new OpenGeniApiError(response.status, await safeText(response));
+    }
+    const events = await response.json();
+    const bytesHeader = response.headers.get("X-OpenGeni-Page-Bytes");
+    const nextHeader = response.headers.get("X-OpenGeni-Next-After");
+    const parsedBytes = bytesHeader === null ? Number.NaN : Number(bytesHeader);
+    const parsedNext = nextHeader === null ? null : Number(nextHeader);
+    return {
+      events,
+      bytes: Number.isSafeInteger(parsedBytes) && parsedBytes >= 0 ? parsedBytes : new TextEncoder().encode(JSON.stringify(events)).byteLength,
+      truncated: response.headers.get("X-OpenGeni-Page-Truncated") === "true",
+      nextAfter: parsedNext !== null && Number.isSafeInteger(parsedNext) && parsedNext >= 0 ? parsedNext : null
+    };
+  }
+  streamWorkspaceControlEvents(workspaceId, options = {}) {
+    return streamWorkspaceControlEvents(this.workspaceControlStreamTransport(workspaceId), options);
+  }
+  workspaceControlStreamTransport(workspaceId) {
+    return {
+      openStream: async (after, signal) => await this.openWorkspaceControlEventStream(workspaceId, {
+        after,
+        ...signal ? { signal } : {}
+      })
+    };
+  }
+  async openWorkspaceControlEventStream(workspaceId, options = {}) {
+    const response = await this.fetchImpl(
+      this.url(`/v1/workspaces/${workspaceId}/control-events/stream`, {
+        after: String(options.after ?? 0)
+      }),
+      {
+        method: "GET",
+        headers: { ...this.headers(), Accept: "text/event-stream" },
+        ...options.signal ? { signal: options.signal } : {}
+      }
+    );
+    assertApiContractResponse(response);
+    if (!response.ok) throw new OpenGeniApiError(response.status, await safeText(response));
+    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
@@ -610,19 +1026,23 @@ var OpenGeniClient = class {
   // synchronous API-direct point query; the fs.changed/git.changed/terminal.pty.*
   // notifications + the PTY output stream arrive on the existing event SSE.
   /** FileSystem: list a directory tree (feeds the Pierre file tree). */
-  async fsList(workspaceId, sessionId, request = {}) {
+  async fsList(workspaceId, sessionId, request = {}, options = {}) {
     return await this.requestJson(
       "POST",
       `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/list`,
-      request
+      request,
+      {},
+      options
     );
   }
   /** FileSystem: read a file (text or base64; binary-safe, size-capped). */
-  async fsRead(workspaceId, sessionId, request) {
+  async fsRead(workspaceId, sessionId, request, options = {}) {
     return await this.requestJson(
       "POST",
       `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/read`,
-      request
+      request,
+      {},
+      options
     );
   }
   /** FileSystem: write a file (last-writer-wins; emits fs.changed). */
@@ -658,19 +1078,23 @@ var OpenGeniClient = class {
     );
   }
   /** Git: working-tree/index status (the Pierre file-status feed). */
-  async gitStatus(workspaceId, sessionId, request = {}) {
+  async gitStatus(workspaceId, sessionId, request = {}, options = {}) {
     return await this.requestJson(
       "POST",
       `/v1/workspaces/${workspaceId}/sessions/${sessionId}/git/status`,
-      request
+      request,
+      {},
+      options
     );
   }
   /** Git: structured diff hunks (the Pierre diff feed). */
-  async gitDiff(workspaceId, sessionId, request = {}) {
+  async gitDiff(workspaceId, sessionId, request = {}, options = {}) {
     return await this.requestJson(
       "POST",
       `/v1/workspaces/${workspaceId}/sessions/${sessionId}/git/diff`,
-      request
+      request,
+      {},
+      options
     );
   }
   /** Git: commit log. */
@@ -693,23 +1117,27 @@ var OpenGeniClient = class {
    *  (tree + per-repo diff + file after-image refs), served from durable storage
    *  WITHOUT warming a machine — the workbench cold-paint source. Returns
    *  `{available:false}` when no capture exists yet (fall back to the live path). */
-  async getWorkspaceCapture(workspaceId, sessionId) {
+  async getWorkspaceCapture(workspaceId, sessionId, options = {}) {
     return await this.requestJson(
       "GET",
-      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/workspace/capture`
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/workspace/capture`,
+      void 0,
+      {},
+      options
     );
   }
   /** Workspace capture: a single file's after-image from the capture (revision
    *  pins a specific one; omitted → latest). Content is inline for small files,
    *  else a short-TTL signed URL; a tooLarge file returns metadata only. */
-  async getWorkspaceCaptureFile(workspaceId, sessionId, path, revision) {
+  async getWorkspaceCaptureFile(workspaceId, sessionId, path, revision, options = {}) {
     const query = { path };
     if (revision !== void 0) query.revision = String(revision);
     return await this.requestJson(
       "GET",
       `/v1/workspaces/${workspaceId}/sessions/${sessionId}/workspace/capture/file`,
       void 0,
-      query
+      query,
+      options
     );
   }
   /** Terminal: run a bounded command, returning buffered stdout/stderr inline. */
@@ -764,10 +1192,13 @@ var OpenGeniClient = class {
    *  liveness the client polls on while `cold`/`warming`. The desktop URL/token
    *  are minted in-process only when the box is warm AND the principal has
    *  acknowledged the un-redacted plane. */
-  async getStreamCapabilities(workspaceId, sessionId) {
+  async getStreamCapabilities(workspaceId, sessionId, options = {}) {
     return await this.requestJson(
       "GET",
-      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/stream-capabilities`
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/stream-capabilities`,
+      void 0,
+      {},
+      options
     );
   }
   /** Record the calling principal's acknowledgment of the un-redacted desktop
@@ -821,7 +1252,14 @@ var OpenGeniClient = class {
    * knowledge of the host setup; safe to call before any auth is established.
    */
   async getClientConfig() {
-    return await this.requestJson("GET", "/v1/config/client");
+    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;
   }
   /** The caller's access context: subject, account + workspace grants, defaults. */
   async getAccessContext() {
@@ -1404,14 +1842,13 @@ var OpenGeniClient = class {
     return logoAssetPath ? `${this.baseUrl}/v1/${logoAssetPath}` : null;
   }
   // --- GitHub ----------------------------------------------------------------------------------
-  /** GitHub App configuration status + a signed install URL when configured. */
+  /** GitHub App configuration status; install/link URLs are null while new binding is disabled. */
   async getGitHubApp(workspaceId) {
     return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/github/app`);
   }
   /**
-   * Browser entry point that plants the CSRF cookie and forwards to GitHub's
-   * install page. Open this in a browser (it redirects); `state` comes from
-   * `getGitHubApp().installUrl` or a github_connect_link tool.
+   * Compatibility URL for previously issued state. New installation binding is
+   * disabled, so the endpoint validates state and terminates with HTTP 410.
    */
   githubConnectUrl(workspaceId, state) {
     return this.url(`/v1/workspaces/${workspaceId}/github/connect`, { state });
@@ -1429,6 +1866,13 @@ var OpenGeniClient = class {
       `/v1/workspaces/${workspaceId}/github/repositories/sync`
     );
   }
+  /** Remove one workspace binding without uninstalling the GitHub App itself. */
+  async unlinkGitHubInstallation(workspaceId, installationId) {
+    await this.requestVoid(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/github/installations/${installationId}`
+    );
+  }
   /** Build a GitHub App manifest + the GitHub URL to submit it to. */
   async createGitHubAppManifest(workspaceId, request = {}) {
     return await this.requestJson(
@@ -1491,7 +1935,8 @@ var OpenGeniClient = class {
     const extra = typeof this.options.headers === "function" ? this.options.headers() : this.options.headers;
     return {
       ...this.options.apiKey ? { Authorization: `Bearer ${this.options.apiKey}` } : {},
-      ...extra
+      ...extra,
+      [OPENGENI_API_CONTRACT_HEADER]: OPENGENI_API_CONTRACT_REVISION
     };
   }
   url(path, query = {}) {
@@ -1591,7 +2036,7 @@ var OpenGeniClient = class {
       { target }
     );
   }
-  async requestJson(method, path, body, query = {}) {
+  async requestJson(method, path, body, query = {}, options = {}) {
     const response = await this.fetchImpl(this.url(path, query), {
       method,
       headers: {
@@ -1599,8 +2044,10 @@ var OpenGeniClient = class {
         Accept: "application/json",
         ...body !== void 0 ? { "Content-Type": "application/json" } : {}
       },
-      ...body !== void 0 ? { body: JSON.stringify(body) } : {}
+      ...body !== void 0 ? { body: JSON.stringify(body) } : {},
+      ...options.signal ? { signal: options.signal } : {}
     });
+    assertApiContractResponse(response);
     if (!response.ok) {
       throw new OpenGeniApiError(response.status, await safeText(response));
     }
@@ -1617,11 +2064,18 @@ var OpenGeniClient = class {
       },
       ...body !== void 0 ? { body: JSON.stringify(body) } : {}
     });
+    assertApiContractResponse(response);
     if (!response.ok) {
       throw new OpenGeniApiError(response.status, await safeText(response));
     }
   }
 };
+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);
+  }
+}
 async function safeText(response) {
   try {
     return await response.text();
@@ -1813,174 +2267,225 @@ function ttydResizeFrame(columns, rows) {
   return TtydClientCommand.RESIZE + JSON.stringify({ columns, rows });
 }
 
-// src/types.ts
-var SESSION_EVENT_TYPES = [
-  "session.created",
-  "session.status.changed",
-  "session.requiresAction",
-  "session.context.compaction.requested",
-  "session.context.compacted",
-  "session.context.compaction.skipped",
-  "session.context.cleared",
-  "user.message",
-  "user.pause",
-  "user.approvalDecision",
-  "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.usage",
-  "tool.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",
-  "session.control.paused",
-  "session.control.resumed",
-  "session.control.steer_requested",
-  "workspace.inference.paused",
-  "workspace.inference.resumed",
-  "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",
-  // Multi-account Codex (P1): the session's inference account changed.
-  "codex.account.switched",
-  // OPE-21 metadata-only per-turn credential selection audit.
-  "codex.credential.selected",
-  // OPE-21 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-surfacing (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"
-];
-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/transcription.ts
+var DEFAULT_WORKSPACE_TRANSCRIPTION_POLICY = {
+  enabled: false,
+  acceptanceId: null,
+  primary: null,
+  language: null,
+  autoDetectLanguage: false,
+  diarization: { enabled: false, maxSpeakers: null },
+  retention: { mode: "none", maxDays: null },
+  privacy: { allowProviderLogging: false, allowProviderTraining: false },
+  fallback: { mode: "disabled", targets: [] },
+  cost: { currency: "USD", maxPerHour: null, maxPerMonth: null }
+};
+function resolveWorkspaceTranscriptionPolicy(settings) {
+  if (!isRecord(settings)) return cloneDefaultPolicy();
+  const candidate = settings.transcription;
+  if (!isWorkspaceTranscriptionPolicy(candidate)) return cloneDefaultPolicy();
+  return {
+    ...candidate,
+    primary: candidate.primary ? normalizeTarget(candidate.primary) : null,
+    language: candidate.language?.trim() ?? null,
+    diarization: { ...candidate.diarization },
+    retention: { ...candidate.retention },
+    privacy: { ...candidate.privacy },
+    fallback: {
+      mode: candidate.fallback.mode,
+      targets: candidate.fallback.targets.map(normalizeTarget)
+    },
+    cost: { ...candidate.cost }
+  };
+}
+function authorizeTranscriptionAdapter(policy, descriptor, selection = { kind: "primary" }) {
+  if (!isWorkspaceTranscriptionPolicy(policy)) {
+    return { authorized: false, reason: "unaccepted" };
+  }
+  if (!policy.enabled) return { authorized: false, reason: "disabled" };
+  if (!policy.acceptanceId) return { authorized: false, reason: "unaccepted" };
+  let target;
+  if (selection.kind === "primary") {
+    target = policy.primary;
+  } else {
+    if (policy.fallback.mode !== "explicit") {
+      return { authorized: false, reason: "fallback_disabled" };
+    }
+    target = policy.fallback.targets[selection.index];
+    if (!target) return { authorized: false, reason: "fallback_unaccepted" };
+  }
+  if (!target) return { authorized: false, reason: "target_missing" };
+  const acceptedTarget = normalizeTarget(target);
+  if (acceptedTarget.provider !== descriptor.provider) {
+    return { authorized: false, reason: "provider_mismatch" };
+  }
+  if (acceptedTarget.model !== descriptor.model) {
+    return { authorized: false, reason: "model_mismatch" };
+  }
+  if (acceptedTarget.credentialMode !== descriptor.credentialMode) {
+    return { authorized: false, reason: "credential_mode_mismatch" };
+  }
+  if (acceptedTarget.region !== descriptor.region) {
+    return { authorized: false, reason: "region_mismatch" };
+  }
+  return {
+    authorized: true,
+    acceptanceId: policy.acceptanceId,
+    target: acceptedTarget,
+    selection
+  };
+}
+function createTranscriptionSessionRequest(input) {
+  const sequenceFloor = input.sequenceFloor ?? 0;
+  if (!Number.isSafeInteger(sequenceFloor) || sequenceFloor < 0) return null;
+  const authorization = authorizeTranscriptionAdapter(
+    input.policy,
+    input.adapter.descriptor,
+    input.selection
+  );
+  if (!authorization.authorized) return null;
+  return {
+    localSessionId: input.localSessionId,
+    policyAcceptanceId: authorization.acceptanceId,
+    selection: authorization.selection,
+    target: { ...authorization.target },
+    language: input.policy.language?.trim() ?? null,
+    autoDetectLanguage: input.policy.autoDetectLanguage,
+    diarization: { ...input.policy.diarization },
+    retention: { ...input.policy.retention },
+    privacy: { ...input.policy.privacy },
+    cost: { ...input.policy.cost },
+    sequenceFloor
+  };
+}
+function cloneDefaultPolicy() {
+  return {
+    ...DEFAULT_WORKSPACE_TRANSCRIPTION_POLICY,
+    diarization: { ...DEFAULT_WORKSPACE_TRANSCRIPTION_POLICY.diarization },
+    retention: { ...DEFAULT_WORKSPACE_TRANSCRIPTION_POLICY.retention },
+    privacy: { ...DEFAULT_WORKSPACE_TRANSCRIPTION_POLICY.privacy },
+    fallback: { mode: "disabled", targets: [] },
+    cost: { ...DEFAULT_WORKSPACE_TRANSCRIPTION_POLICY.cost }
+  };
+}
+function isWorkspaceTranscriptionPolicy(value) {
+  if (!isRecord(value) || typeof value.enabled !== "boolean") return false;
+  if (!hasOnlyKeys(value, [
+    "enabled",
+    "acceptanceId",
+    "primary",
+    "language",
+    "autoDetectLanguage",
+    "diarization",
+    "retention",
+    "privacy",
+    "fallback",
+    "cost"
+  ])) {
+    return false;
+  }
+  if (!(value.acceptanceId === null || isUuid(value.acceptanceId))) return false;
+  if (!(value.primary === null || isTarget(value.primary))) return false;
+  if (!(value.language === null || isBoundedString(value.language, 64))) return false;
+  if (typeof value.autoDetectLanguage !== "boolean") return false;
+  if (!isRecord(value.diarization) || !hasOnlyKeys(value.diarization, ["enabled", "maxSpeakers"]) || typeof value.diarization.enabled !== "boolean" || !(value.diarization.maxSpeakers === null || isBoundedInteger(value.diarization.maxSpeakers, 100) && value.diarization.maxSpeakers >= 2)) {
+    return false;
+  }
+  if (!value.diarization.enabled && value.diarization.maxSpeakers !== null) return false;
+  if (!isRecord(value.retention) || !hasOnlyKeys(value.retention, ["mode", "maxDays"])) {
+    return false;
+  }
+  if (value.retention.mode !== "none" && value.retention.mode !== "provider-policy") return false;
+  if (!(value.retention.maxDays === null || isBoundedInteger(value.retention.maxDays, 3650))) {
+    return false;
+  }
+  if (!isRecord(value.privacy) || !hasOnlyKeys(value.privacy, ["allowProviderLogging", "allowProviderTraining"]) || typeof value.privacy.allowProviderLogging !== "boolean" || typeof value.privacy.allowProviderTraining !== "boolean") {
+    return false;
+  }
+  if (!isRecord(value.fallback) || !hasOnlyKeys(value.fallback, ["mode", "targets"])) {
+    return false;
+  }
+  if (value.fallback.mode !== "disabled" && value.fallback.mode !== "explicit") return false;
+  if (!Array.isArray(value.fallback.targets) || value.fallback.targets.length > 8 || !value.fallback.targets.every(isTarget)) {
+    return false;
+  }
+  if (value.fallback.mode === "disabled" && value.fallback.targets.length !== 0) return false;
+  if (value.fallback.mode === "explicit" && value.fallback.targets.length === 0) return false;
+  if (!isRecord(value.cost) || !hasOnlyKeys(value.cost, ["currency", "maxPerHour", "maxPerMonth"]) || value.cost.currency !== "USD") {
+    return false;
+  }
+  if (!isNullableBoundedNumber(value.cost.maxPerHour, 1e4)) return false;
+  if (!isNullableBoundedNumber(value.cost.maxPerMonth, 1e6)) return false;
+  if (value.enabled && (!value.acceptanceId || !value.primary)) return false;
+  if (value.enabled && !value.autoDetectLanguage && value.language === null) return false;
+  if (value.autoDetectLanguage && value.language !== null) return false;
+  const targets = [value.primary, ...value.fallback.targets].filter(
+    (target) => target !== null
+  );
+  if (new Set(targets.map(targetKey)).size !== targets.length) return false;
+  return true;
+}
+function targetKey(target) {
+  return [
+    target.provider.trim(),
+    target.model?.trim() ?? "",
+    target.credentialMode,
+    target.credentialConnectionId ?? "",
+    target.region?.trim() ?? ""
+  ].join("\0");
+}
+function isTarget(value) {
+  if (!isRecord(value)) return false;
+  if (!hasOnlyKeys(value, ["provider", "model", "credentialMode", "credentialConnectionId", "region"])) {
+    return false;
+  }
+  if (!isBoundedString(value.provider, 128)) return false;
+  if (!(value.model === null || isBoundedString(value.model, 256))) return false;
+  if (value.credentialMode !== "managed" && value.credentialMode !== "byok") return false;
+  if (value.provider.trim() === "azure-speech" && value.credentialMode !== "byok") return false;
+  if (!(value.credentialConnectionId === null || isUuid(value.credentialConnectionId))) {
+    return false;
+  }
+  if (!(value.region === null || isBoundedString(value.region, 128))) return false;
+  if (value.credentialMode === "byok" && value.credentialConnectionId === null) return false;
+  if (value.credentialMode === "managed" && value.credentialConnectionId !== null) return false;
+  return true;
+}
+function normalizeTarget(target) {
+  return {
+    provider: target.provider.trim(),
+    model: target.model?.trim() ?? null,
+    credentialMode: target.credentialMode,
+    credentialConnectionId: target.credentialConnectionId,
+    region: target.region?.trim() ?? null
+  };
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function hasOnlyKeys(value, keys) {
+  const accepted = new Set(keys);
+  return Object.keys(value).every((key) => accepted.has(key));
+}
+function isBoundedString(value, maximum) {
+  return typeof value === "string" && value.trim().length > 0 && value.length <= maximum;
+}
+function isUuid(value) {
+  return typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+function isBoundedInteger(value, maximum) {
+  return Number.isInteger(value) && value >= 0 && value <= maximum;
+}
+function isNullableBoundedNumber(value, maximum) {
+  return value === null || typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= maximum;
+}
 export {
+  DEFAULT_WORKSPACE_TRANSCRIPTION_POLICY,
   KNOWN_PERMISSIONS,
   KNOWN_USAGE_EVENT_TYPES,
+  OPENGENI_API_CONTRACT_HEADER,
+  OPENGENI_API_CONTRACT_REVISION,
+  OpenGeniApiContractMismatchError,
   OpenGeniApiError,
   OpenGeniClient,
   OpenGeniStreamError,
@@ -1989,16 +2494,20 @@ export {
   TtydClientCommand,
   TtydServerCommand,
   applyUrlRotation,
+  authorizeTranscriptionAdapter,
+  createTranscriptionSessionRequest,
   desktopSocketUrl,
   formatSseEvent,
   isRetryableStreamError,
   nextDesktopState,
   parseSseStream,
   proxySessionEventStream,
+  resolveWorkspaceTranscriptionPolicy,
   resumeSequenceFromRequest,
   sessionEventsToSseResponse,
   sessionEventsToSseStream,
   streamSessionEvents,
+  streamWorkspaceControlEvents,
   terminalSocketUrl,
   ttydAuthFrame,
   ttydInputFrame,