@opengeni/sdk 0.13.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/sdk",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Framework-agnostic TypeScript SDK for the OpenGeni API: typed client, session lifecycle, SSE event streaming with reconnect + replay-by-sequence, and proxy re-streaming helpers.",
   "license": "Apache-2.0",
   "repository": {

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,
@@ -90,8 +94,15 @@ import type {
   SessionMcpCredentialUpdateInput,
   SessionQueueSnapshot,
   SessionQueueMutationResponse,
+  ComposerDraft,
+  DeleteSessionQueueItemRequest,
+  EditSessionQueueItemRequest,
+  MoveSessionQueueItemRequest,
+  SaveComposerDraftRequest,
+  SteerSessionQueueItemRequest,
   SessionControlResponse,
   WorkspaceInferenceControlResponse,
+  WorkspaceControlEvent,
   SessionTurn,
   // Stream surfacing (Phase 5): capability negotiation + viewer lifecycle + config.
   SessionCapabilities,
@@ -161,6 +172,7 @@ 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>;
 
@@ -182,8 +194,8 @@ export type SendMessageInput = {
   model?: string;
   reasoningEffort?: ReasoningEffort;
   clientEventId?: string;
-  expectedControlGeneration?: number;
-  expectedWorkspaceInferenceGeneration?: number;
+  controlEtag?: string;
+  expectedDraftRevision?: number;
   mcpCredentialUpdates?: SessionMcpCredentialUpdateInput[];
 };
 
@@ -276,7 +288,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 +306,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. */
@@ -551,14 +546,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(
@@ -619,6 +614,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 +633,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 +708,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 +724,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,18 +750,60 @@ 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.requestJson<WorkspaceControlEvent[]>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/control-events`,
+      undefined,
+      {
+        ...(options.after !== undefined ? { after: String(options.after) } : {}),
+        ...(options.limit !== undefined ? { limit: String(options.limit) } : {}),
+      },
     );
   }
 
+  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;
+  }
+
   /**
    * Steer: atomically put this prompt at the head and supersede the current
    * inference. The client performs one request and renders server order.
@@ -1121,7 +1218,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. */
@@ -2058,6 +2162,7 @@ export class OpenGeniClient {
     return {
       ...(this.options.apiKey ? { Authorization: `Bearer ${this.options.apiKey}` } : {}),
       ...extra,
+      [OPENGENI_API_CONTRACT_HEADER]: OPENGENI_API_CONTRACT_REVISION,
     };
   }
 
@@ -2208,6 +2313,7 @@ export class OpenGeniClient {
       },
       ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
     });
+    assertApiContractResponse(response);
     if (!response.ok) {
       throw new OpenGeniApiError(response.status, await safeText(response));
     }
@@ -2225,12 +2331,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();

package/src/errors.ts

@@ -11,6 +11,19 @@ export class OpenGeniApiError extends Error {
   }
 }
 
+/** The browser bundle and API disagree about their state-changing wire contract. */
+export class OpenGeniApiContractMismatchError extends Error {
+  readonly expected: string;
+  readonly actual: string;
+
+  constructor(expected: string, actual: string) {
+    super(`OpenGeni API contract mismatch: client expects ${expected}, API serves ${actual}`);
+    this.name = "OpenGeniApiContractMismatchError";
+    this.expected = expected;
+    this.actual = actual;
+  }
+}
+
 /** Error for an unrecoverable event-stream condition (not a transient drop). */
 export class OpenGeniStreamError extends Error {
   constructor(message: string) {

package/src/index.ts

@@ -5,7 +5,12 @@ export type {
   SendMessageInput,
   SteerMessageResult,
 } from "./client";
-export { OpenGeniApiError, OpenGeniStreamError, isRetryableStreamError } from "./errors";
+export {
+  OpenGeniApiContractMismatchError,
+  OpenGeniApiError,
+  OpenGeniStreamError,
+  isRetryableStreamError,
+} from "./errors";
 export {
   formatSseEvent,
   proxySessionEventStream,
@@ -43,7 +48,15 @@ export type {
   StreamConnectionState,
   StreamSessionEventsOptions,
 } from "./stream";
-export { KNOWN_PERMISSIONS, KNOWN_USAGE_EVENT_TYPES, SESSION_EVENT_TYPES } from "./types";
+export { streamWorkspaceControlEvents } from "./workspace-control-stream";
+export type { WorkspaceControlStreamTransport } from "./workspace-control-stream";
+export {
+  KNOWN_PERMISSIONS,
+  KNOWN_USAGE_EVENT_TYPES,
+  OPENGENI_API_CONTRACT_HEADER,
+  OPENGENI_API_CONTRACT_REVISION,
+  SESSION_EVENT_TYPES,
+} from "./types";
 export type {
   AccessContext,
   AccessGrant,
@@ -191,6 +204,16 @@ export type {
   SessionQueueMutationResponse,
   SessionQueueSnapshot,
   SessionControlResponse,
+  ComposerDraft,
+  DeleteSessionQueueItemRequest,
+  EditSessionQueueItemRequest,
+  EffectiveControlBlocker,
+  EffectiveControlResumeOption,
+  EffectiveSessionControl,
+  MoveSessionQueueItemRequest,
+  SaveComposerDraftRequest,
+  SessionCommandReceipt,
+  SteerSessionQueueItemRequest,
   WorkspaceInferenceControlResponse,
   SessionSystemUpdate,
   SessionSystemUpdateKind,
@@ -306,6 +329,7 @@ export type {
   UserApprovalDecisionEventInput,
   UserMessageEventInput,
   Workspace,
+  WorkspaceControlEvent,
   VariableSet,
   VariableSetVariableMetadata,
   Rig,

package/src/stream.ts

@@ -34,6 +34,8 @@ export type StreamSessionEventsOptions = {
    * reconnects = N+1 total open-stream calls). Defaults to unlimited.
    */
   maxReconnectAttempts?: number;
+  /** Await authoritative client reconciliation before exposing `live`. */
+  beforeLive?: (() => void | Promise<void>) | undefined;
   onStateChange?: (state: StreamConnectionState) => void;
 };
 
@@ -75,6 +77,7 @@ export async function* streamSessionEvents(
       everConnected = true;
       failedAttempts = 0;
       delayMs = baseDelayMs;
+      await options.beforeLive?.();
       options.onStateChange?.("live");
       for await (const message of parseSseStream(body)) {
         // Re-check after every yield resumption: an abort from the consumer