@opengeni/sdk 0.13.0 → 0.20.0

package/src/client.ts

@@ -1,9 +1,13 @@
-import { OpenGeniApiError } from "./errors";
+import { OpenGeniApiContractMismatchError, OpenGeniApiError } from "./errors";
 import {
   streamSessionEvents,
   type SessionEventStreamTransport,
   type StreamSessionEventsOptions,
 } from "./stream";
+import {
+  streamWorkspaceControlEvents,
+  type WorkspaceControlStreamTransport,
+} from "./workspace-control-stream";
 import type {
   AccessContext,
   AddWorkspaceMemberRequest,
@@ -42,6 +46,7 @@ import type {
   CreateKnowledgeMemoryRequest,
   CreateScheduledTaskRequest,
   CreateSessionRequest,
+  CreateSessionResponse,
   CreateVariableSetRequest,
   CreateRigRequest,
   CreateWorkspaceRequest,
@@ -85,14 +90,25 @@ import type {
   SessionListResponse,
   UpdateSessionPinRequest,
   SessionEvent,
+  SessionEventListOptions,
+  SessionEventPage,
   SessionGoal,
+  SessionHumanInputRequest,
   SessionLineageResponse,
   SessionMcpCredentialUpdateInput,
   SessionQueueSnapshot,
   SessionQueueMutationResponse,
+  ComposerDraft,
+  DeleteSessionQueueItemRequest,
+  EditSessionQueueItemRequest,
+  MoveSessionQueueItemRequest,
+  SaveComposerDraftRequest,
+  SteerSessionQueueItemRequest,
   SessionControlResponse,
   WorkspaceInferenceControlResponse,
+  WorkspaceControlEvent,
   SessionTurn,
+  SubmitHumanInputResponseRequest,
   // Stream surfacing (Phase 5): capability negotiation + viewer lifecycle + config.
   SessionCapabilities,
   AttachViewerRequest,
@@ -122,7 +138,7 @@ import type {
   GitLogResponse,
   GitShowRequest,
   GitShowResponse,
-  // Workbench v2 turn-end capture reads (M2, dossier §10.3).
+  // Workbench v2 turn-end capture reads (M2).
   GetWorkspaceCaptureResponse,
   GetWorkspaceCaptureFileResponse,
   TerminalExecRequest,
@@ -161,9 +177,17 @@ import type {
   OAuthStartRequest,
   OAuthStartResponse,
 } from "./types";
+import { OPENGENI_API_CONTRACT_HEADER, OPENGENI_API_CONTRACT_REVISION } from "./types";
 
 export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 
+export type WorkspaceControlEventPage = {
+  events: WorkspaceControlEvent[];
+  bytes: number;
+  truncated: boolean;
+  nextAfter: number | null;
+};
+
 export type OpenGeniClientOptions = {
   /** Base URL of the OpenGeni API, e.g. `https://api.example.com`. */
   baseUrl: string;
@@ -175,15 +199,22 @@ export type OpenGeniClientOptions = {
   fetch?: FetchLike;
 };
 
+/** Per-request cancellation for identity-scoped, side-effect-free reads. */
+export type OpenGeniRequestOptions = {
+  signal?: AbortSignal | undefined;
+};
+
 export type SendMessageInput = {
   text: string;
+  /** System instructions scoped to this exact turn; never visible timeline text. */
+  turnInstructions?: string;
   resources?: ResourceRef[];
   tools?: ToolRef[];
   model?: string;
   reasoningEffort?: ReasoningEffort;
   clientEventId?: string;
-  expectedControlGeneration?: number;
-  expectedWorkspaceInferenceGeneration?: number;
+  controlEtag?: string;
+  expectedDraftRevision?: number;
   mcpCredentialUpdates?: SessionMcpCredentialUpdateInput[];
 };
 
@@ -213,8 +244,11 @@ export class OpenGeniClient {
 
   // --- Session lifecycle ---------------------------------------------------
 
-  async createSession(workspaceId: string, request: CreateSessionRequest): Promise<Session> {
-    return await this.requestJson<Session>(
+  async createSession(
+    workspaceId: string,
+    request: CreateSessionRequest,
+  ): Promise<CreateSessionResponse> {
+    return await this.requestJson<CreateSessionResponse>(
       "POST",
       `/v1/workspaces/${workspaceId}/sessions`,
       request,
@@ -276,7 +310,7 @@ export class OpenGeniClient {
       search?: string;
     } = {},
   ): Promise<SessionListResponse> {
-    const response = await this.requestJson<SessionListResponse | Session[]>(
+    return await this.requestJson<SessionListResponse>(
       "GET",
       `/v1/workspaces/${workspaceId}/sessions`,
       undefined,
@@ -294,23 +328,6 @@ export class OpenGeniClient {
           : {}),
       },
     );
-    if (Array.isArray(response)) {
-      // Rolling/same-major compatibility: an older API ignores `view=page` and
-      // returns the historical array. That is an honest one-page projection;
-      // never pretend it honored a cursor supplied directly by a caller.
-      if (options.cursor) {
-        throw new Error("The connected OpenGeni API does not support stable session-page cursors");
-      }
-      // Older APIs ignore unknown query parameters. Treating their unfiltered
-      // array as a successful search would be worse than an explicit rolling-
-      // upgrade error (and client-side filtering cannot recover matches beyond
-      // the old endpoint's bounded first page).
-      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. */
@@ -358,7 +375,7 @@ export class OpenGeniClient {
    */
   async listMachines(
     workspaceId: string,
-    options: { sessionId?: string } = {},
+    options: { sessionId?: string; signal?: AbortSignal } = {},
   ): Promise<MachinesResponse> {
     return await this.requestJson<MachinesResponse>(
       "GET",
@@ -367,6 +384,7 @@ export class OpenGeniClient {
       {
         ...(options.sessionId !== undefined ? { sessionId: options.sessionId } : {}),
       },
+      { signal: options.signal },
     );
   }
 
@@ -498,27 +516,101 @@ export class OpenGeniClient {
   // --- 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: string,
     sessionId: string,
-    options: { after?: number; before?: number; limit?: number; compact?: boolean } = {},
+    options: SessionEventListOptions = {},
   ): Promise<SessionEvent[]> {
-    return await this.requestJson<SessionEvent[]>(
-      "GET",
-      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/events`,
-      undefined,
-      {
+    return (await this.listEventPage(workspaceId, sessionId, options)).events;
+  }
+
+  /** Bounded durable/monitoring page plus exact projection and cursor facts. */
+  async listEventPage(
+    workspaceId: string,
+    sessionId: string,
+    options: SessionEventListOptions = {},
+  ): Promise<SessionEventPage> {
+    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 !== undefined ? { after: String(options.after) } : {}),
         ...(options.before !== undefined ? { before: String(options.before) } : {}),
         ...(options.limit !== undefined ? { limit: String(options.limit) } : {}),
         ...(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()) as SessionEvent[];
+    const integerHeader = (name: string): number | null => {
+      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. */
@@ -551,14 +643,14 @@ export class OpenGeniClient {
   async pauseSession(
     workspaceId: string,
     sessionId: string,
-    options: { reason?: string; clientEventId?: string } = {},
-  ): Promise<SessionEvent> {
-    return (
-      await this.controlSession(workspaceId, sessionId, {
-        mode: "pause",
-        ...options,
-      })
-    ).event;
+    options: { reason?: string; clientEventId?: string; expectedControlEtag?: string } = {},
+  ): Promise<SessionControlResponse> {
+    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(
@@ -579,6 +671,47 @@ export class OpenGeniClient {
     });
   }
 
+  async listHumanInputRequests(
+    workspaceId: string,
+    sessionId: string,
+    options: {
+      status?: SessionHumanInputRequest["status"];
+    } = {},
+  ): Promise<SessionHumanInputRequest[]> {
+    const result = await this.requestJson<{ requests: SessionHumanInputRequest[] }>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/human-input-requests`,
+      undefined,
+      options.status ? { status: options.status } : undefined,
+    );
+    return result.requests;
+  }
+
+  async getHumanInputRequest(
+    workspaceId: string,
+    sessionId: string,
+    requestId: string,
+  ): Promise<SessionHumanInputRequest> {
+    return await this.requestJson<SessionHumanInputRequest>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/human-input-requests/${requestId}`,
+    );
+  }
+
+  async submitHumanInputResponse(
+    workspaceId: string,
+    sessionId: string,
+    requestId: string,
+    response: SubmitHumanInputResponseRequest,
+    options: { clientEventId?: string } = {},
+  ): Promise<SessionEvent> {
+    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
@@ -619,6 +752,7 @@ export class OpenGeniClient {
       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));
     }
@@ -637,15 +771,73 @@ export class OpenGeniClient {
     );
   }
 
-  async cancelQueueItem(
+  async moveQueueItem(
+    workspaceId: string,
+    sessionId: string,
+    turnId: string,
+    request: MoveSessionQueueItemRequest,
+  ): Promise<SessionQueueMutationResponse> {
+    return await this.requestJson<SessionQueueMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/queue/${turnId}/move`,
+      request,
+    );
+  }
+
+  async editQueueItem(
+    workspaceId: string,
+    sessionId: string,
+    turnId: string,
+    request: EditSessionQueueItemRequest,
+  ): Promise<SessionQueueMutationResponse> {
+    return await this.requestJson<SessionQueueMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/queue/${turnId}/edit`,
+      request,
+    );
+  }
+
+  async steerQueueItem(
+    workspaceId: string,
+    sessionId: string,
+    turnId: string,
+    request: SteerSessionQueueItemRequest,
+  ): Promise<SessionQueueMutationResponse> {
+    return await this.requestJson<SessionQueueMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/queue/${turnId}/steer`,
+      request,
+    );
+  }
+
+  async deleteQueueItem(
     workspaceId: string,
     sessionId: string,
     turnId: string,
-    request: { expectedQueueVersion: number; expectedItemVersion: number; reason?: string },
+    request: DeleteSessionQueueItemRequest,
   ): Promise<SessionQueueMutationResponse> {
     return await this.requestJson<SessionQueueMutationResponse>(
       "POST",
-      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/queue/${turnId}/cancel`,
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/queue/${turnId}/delete`,
+      request,
+    );
+  }
+
+  async getComposerDraft(workspaceId: string, sessionId: string): Promise<ComposerDraft> {
+    return await this.requestJson<ComposerDraft>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/composer-draft`,
+    );
+  }
+
+  async saveComposerDraft(
+    workspaceId: string,
+    sessionId: string,
+    request: SaveComposerDraftRequest,
+  ): Promise<ComposerDraft> {
+    return await this.requestJson<ComposerDraft>(
+      "PUT",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/composer-draft`,
       request,
     );
   }
@@ -654,12 +846,10 @@ export class OpenGeniClient {
     workspaceId: string,
     sessionId: string,
     request: {
-      mode: "pause" | "resume";
+      action: "pause" | "resume";
       reason?: string;
-      clientEventId?: string;
-      expectedControlState?: "active" | "paused";
-      expectedControlGeneration?: number;
-      expectedWorkspaceInferenceGeneration?: number;
+      clientEventId: string;
+      expectedControlEtag?: string;
     },
   ): Promise<SessionControlResponse> {
     return await this.requestJson<SessionControlResponse>(
@@ -672,20 +862,23 @@ export class OpenGeniClient {
   async resumeSession(
     workspaceId: string,
     sessionId: string,
-    options: { reason?: string; clientEventId?: string } = {},
+    options: { reason?: string; clientEventId?: string; expectedControlEtag?: string } = {},
   ): Promise<SessionControlResponse> {
-    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: string,
     request: {
-      state: "active" | "paused";
-      reason: string;
+      action: "pause" | "resume";
+      reason?: string;
       clientEventId: string;
-      expectedState: "active" | "paused";
-      expectedGeneration: number;
-      exceptSessionIds?: string[];
+      expectedRevision?: number;
     },
   ): Promise<WorkspaceInferenceControlResponse> {
     return await this.requestJson<WorkspaceInferenceControlResponse>(
@@ -695,16 +888,88 @@ export class OpenGeniClient {
     );
   }
 
-  /** Cancel a queued turn before it is claimed. Returns the cancelled turn. */
-  async deleteQueuedTurn(
+  async listWorkspaceControlEvents(
     workspaceId: string,
-    sessionId: string,
-    turnId: string,
-  ): Promise<SessionTurn> {
-    return await this.requestJson<SessionTurn>(
-      "DELETE",
-      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/turns/${turnId}`,
+    options: { after?: number; limit?: number } = {},
+  ): Promise<WorkspaceControlEvent[]> {
+    return (await this.listWorkspaceControlEventPage(workspaceId, options)).events;
+  }
+
+  /** Count/byte-bounded page plus an explicit continuation cursor. */
+  async listWorkspaceControlEventPage(
+    workspaceId: string,
+    options: { after?: number; limit?: number } = {},
+  ): Promise<WorkspaceControlEventPage> {
+    const response = await this.fetchImpl(
+      this.url(`/v1/workspaces/${workspaceId}/control-events`, {
+        ...(options.after !== undefined ? { after: String(options.after) } : {}),
+        ...(options.limit !== undefined ? { 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()) as WorkspaceControlEvent[];
+    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: string,
+    options: StreamSessionEventsOptions = {},
+  ): AsyncGenerator<WorkspaceControlEvent, void, void> {
+    return streamWorkspaceControlEvents(this.workspaceControlStreamTransport(workspaceId), options);
+  }
+
+  workspaceControlStreamTransport(workspaceId: string): WorkspaceControlStreamTransport {
+    return {
+      openStream: async (after, signal) =>
+        await this.openWorkspaceControlEventStream(workspaceId, {
+          after,
+          ...(signal ? { signal } : {}),
+        }),
+    };
+  }
+
+  async openWorkspaceControlEventStream(
+    workspaceId: string,
+    options: { after?: number; signal?: AbortSignal } = {},
+  ): Promise<ReadableStream<Uint8Array>> {
+    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;
   }
 
   /**
@@ -806,11 +1071,14 @@ export class OpenGeniClient {
     workspaceId: string,
     sessionId: string,
     request: FsListRequest = {},
+    options: OpenGeniRequestOptions = {},
   ): Promise<FsListResponse> {
     return await this.requestJson<FsListResponse>(
       "POST",
       `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/list`,
       request,
+      {},
+      options,
     );
   }
 
@@ -819,11 +1087,14 @@ export class OpenGeniClient {
     workspaceId: string,
     sessionId: string,
     request: FsReadRequest,
+    options: OpenGeniRequestOptions = {},
   ): Promise<FsReadResponse> {
     return await this.requestJson<FsReadResponse>(
       "POST",
       `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/read`,
       request,
+      {},
+      options,
     );
   }
 
@@ -884,11 +1155,14 @@ export class OpenGeniClient {
     workspaceId: string,
     sessionId: string,
     request: GitStatusRequest = {},
+    options: OpenGeniRequestOptions = {},
   ): Promise<GitStatusResponse> {
     return await this.requestJson<GitStatusResponse>(
       "POST",
       `/v1/workspaces/${workspaceId}/sessions/${sessionId}/git/status`,
       request,
+      {},
+      options,
     );
   }
 
@@ -897,11 +1171,14 @@ export class OpenGeniClient {
     workspaceId: string,
     sessionId: string,
     request: GitDiffRequest = {},
+    options: OpenGeniRequestOptions = {},
   ): Promise<GitDiffResponse> {
     return await this.requestJson<GitDiffResponse>(
       "POST",
       `/v1/workspaces/${workspaceId}/sessions/${sessionId}/git/diff`,
       request,
+      {},
+      options,
     );
   }
 
@@ -938,10 +1215,14 @@ export class OpenGeniClient {
   async getWorkspaceCapture(
     workspaceId: string,
     sessionId: string,
+    options: OpenGeniRequestOptions = {},
   ): Promise<GetWorkspaceCaptureResponse> {
     return await this.requestJson<GetWorkspaceCaptureResponse>(
       "GET",
       `/v1/workspaces/${workspaceId}/sessions/${sessionId}/workspace/capture`,
+      undefined,
+      {},
+      options,
     );
   }
 
@@ -953,6 +1234,7 @@ export class OpenGeniClient {
     sessionId: string,
     path: string,
     revision?: number,
+    options: OpenGeniRequestOptions = {},
   ): Promise<GetWorkspaceCaptureFileResponse> {
     const query: Record<string, string> = { path };
     if (revision !== undefined) query.revision = String(revision);
@@ -961,6 +1243,7 @@ export class OpenGeniClient {
       `/v1/workspaces/${workspaceId}/sessions/${sessionId}/workspace/capture/file`,
       undefined,
       query,
+      options,
     );
   }
 
@@ -1045,10 +1328,14 @@ export class OpenGeniClient {
   async getStreamCapabilities(
     workspaceId: string,
     sessionId: string,
+    options: OpenGeniRequestOptions = {},
   ): Promise<SessionCapabilities> {
     return await this.requestJson<SessionCapabilities>(
       "GET",
       `/v1/workspaces/${workspaceId}/sessions/${sessionId}/stream-capabilities`,
+      undefined,
+      {},
+      options,
     );
   }
 
@@ -1121,7 +1408,14 @@ export class OpenGeniClient {
    * knowledge of the host setup; safe to call before any auth is established.
    */
   async getClientConfig(): Promise<ClientConfig> {
-    return await this.requestJson<ClientConfig>("GET", "/v1/config/client");
+    const config = await this.requestJson<ClientConfig>("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. */
@@ -1944,15 +2238,14 @@ export class OpenGeniClient {
 
   // --- 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: string): Promise<GitHubAppInfo> {
     return await this.requestJson<GitHubAppInfo>("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: string, state: string): string {
     return this.url(`/v1/workspaces/${workspaceId}/github/connect`, { state });
@@ -1973,6 +2266,14 @@ export class OpenGeniClient {
     );
   }
 
+  /** Remove one workspace binding without uninstalling the GitHub App itself. */
+  async unlinkGitHubInstallation(workspaceId: string, installationId: number): Promise<void> {
+    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: string,
@@ -2058,6 +2359,7 @@ export class OpenGeniClient {
     return {
       ...(this.options.apiKey ? { Authorization: `Bearer ${this.options.apiKey}` } : {}),
       ...extra,
+      [OPENGENI_API_CONTRACT_HEADER]: OPENGENI_API_CONTRACT_REVISION,
     };
   }
 
@@ -2198,6 +2500,7 @@ export class OpenGeniClient {
     path: string,
     body?: unknown,
     query: Record<string, string> = {},
+    options: OpenGeniRequestOptions = {},
   ): Promise<T> {
     const response = await this.fetchImpl(this.url(path, query), {
       method,
@@ -2207,7 +2510,9 @@ export class OpenGeniClient {
         ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
       },
       ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+      ...(options.signal ? { signal: options.signal } : {}),
     });
+    assertApiContractResponse(response);
     if (!response.ok) {
       throw new OpenGeniApiError(response.status, await safeText(response));
     }
@@ -2225,12 +2530,20 @@ export class OpenGeniClient {
       },
       ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
     });
+    assertApiContractResponse(response);
     if (!response.ok) {
       throw new OpenGeniApiError(response.status, await safeText(response));
     }
   }
 }
 
+function assertApiContractResponse(response: Response): void {
+  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: Response): Promise<string> {
   try {
     return await response.text();