@opengeni/sdk 0.15.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/sdk",
-  "version": "0.15.0",
+  "version": "0.20.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

@@ -46,6 +46,7 @@ import type {
   CreateKnowledgeMemoryRequest,
   CreateScheduledTaskRequest,
   CreateSessionRequest,
+  CreateSessionResponse,
   CreateVariableSetRequest,
   CreateRigRequest,
   CreateWorkspaceRequest,
@@ -89,7 +90,10 @@ import type {
   SessionListResponse,
   UpdateSessionPinRequest,
   SessionEvent,
+  SessionEventListOptions,
+  SessionEventPage,
   SessionGoal,
+  SessionHumanInputRequest,
   SessionLineageResponse,
   SessionMcpCredentialUpdateInput,
   SessionQueueSnapshot,
@@ -104,6 +108,7 @@ import type {
   WorkspaceInferenceControlResponse,
   WorkspaceControlEvent,
   SessionTurn,
+  SubmitHumanInputResponseRequest,
   // Stream surfacing (Phase 5): capability negotiation + viewer lifecycle + config.
   SessionCapabilities,
   AttachViewerRequest,
@@ -133,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,
@@ -176,6 +181,13 @@ import { OPENGENI_API_CONTRACT_HEADER, OPENGENI_API_CONTRACT_REVISION } from "./
 
 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;
@@ -187,8 +199,15 @@ 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;
@@ -225,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,
@@ -353,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",
@@ -362,6 +384,7 @@ export class OpenGeniClient {
       {
         ...(options.sessionId !== undefined ? { sessionId: options.sessionId } : {}),
       },
+      { signal: options.signal },
     );
   }
 
@@ -493,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. */
@@ -574,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
@@ -754,15 +892,45 @@ export class OpenGeniClient {
     workspaceId: string,
     options: { after?: number; limit?: number } = {},
   ): Promise<WorkspaceControlEvent[]> {
-    return await this.requestJson<WorkspaceControlEvent[]>(
-      "GET",
-      `/v1/workspaces/${workspaceId}/control-events`,
-      undefined,
-      {
+    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(
@@ -903,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,
     );
   }
 
@@ -916,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,
     );
   }
 
@@ -981,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,
     );
   }
 
@@ -994,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,
     );
   }
 
@@ -1035,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,
     );
   }
 
@@ -1050,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);
@@ -1058,6 +1243,7 @@ export class OpenGeniClient {
       `/v1/workspaces/${workspaceId}/sessions/${sessionId}/workspace/capture/file`,
       undefined,
       query,
+      options,
     );
   }
 
@@ -1142,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,
     );
   }
 
@@ -2048,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 });
@@ -2077,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,
@@ -2303,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,
@@ -2312,6 +2510,7 @@ 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) {

package/src/index.ts

@@ -2,8 +2,10 @@ export { OpenGeniClient } from "./client";
 export type {
   FetchLike,
   OpenGeniClientOptions,
+  OpenGeniRequestOptions,
   SendMessageInput,
   SteerMessageResult,
+  WorkspaceControlEventPage,
 } from "./client";
 export {
   OpenGeniApiContractMismatchError,
@@ -50,6 +52,34 @@ export type {
 } from "./stream";
 export { streamWorkspaceControlEvents } from "./workspace-control-stream";
 export type { WorkspaceControlStreamTransport } from "./workspace-control-stream";
+export {
+  DEFAULT_WORKSPACE_TRANSCRIPTION_POLICY,
+  authorizeTranscriptionAdapter,
+  createTranscriptionSessionRequest,
+  resolveWorkspaceTranscriptionPolicy,
+} from "./transcription";
+export type {
+  TranscriptionAdapter,
+  TranscriptionAdapterDescriptor,
+  TranscriptionAdapterStartContext,
+  TranscriptionAuthorization,
+  TranscriptionCredentialMode,
+  TranscriptionDiagnostic,
+  TranscriptionErrorCode,
+  TranscriptionEvent,
+  TranscriptionEventListener,
+  TranscriptionLifecycleStatus,
+  TranscriptionPolicyBlockReason,
+  TranscriptionResultMetadata,
+  TranscriptionSession,
+  TranscriptionSessionRequest,
+  TranscriptionSpeaker,
+  TranscriptionTargetSelection,
+  TranscriptionTimeSpan,
+  TranscriptionWord,
+  WorkspaceTranscriptionPolicy,
+  WorkspaceTranscriptionTarget,
+} from "./transcription";
 export {
   KNOWN_PERMISSIONS,
   KNOWN_USAGE_EVENT_TYPES,
@@ -141,14 +171,21 @@ export type {
   EntitlementValue,
   EntitlementsMode,
   FileAsset,
+  HumanInputAnswer,
+  HumanInputOption,
+  HumanInputQuestion,
+  HumanInputQuestionKind,
+  HumanInputResponse,
   FileDownloadUrlResponse,
   FileResourceRef,
   FileStatus,
   FileUploadData,
   GetPackResponse,
   GitHubAppInfo,
+  GitHubInstallationBinding,
   GitHubRepositoriesResponse,
   GitHubRepository,
+  GitHubRepositoryScope,
   GoalSpec,
   IntegrationClientMetadata,
   KnownPermission,
@@ -161,6 +198,8 @@ export type {
   KnowledgeSourceKind,
   KnowledgeSourceRef,
   GitCredentialProvider,
+  GitCredentialBindingId,
+  GitRepositoryAccess,
   ListApiKeysResponse,
   ListConnectionsResponse,
   ListPacksResponse,
@@ -244,16 +283,27 @@ export type {
   ViewerHeartbeatRequest,
   ViewerHeartbeatResponse,
   SessionEvent,
+  SessionEventListOptions,
+  SessionEventPage,
+  SessionEventPayloadMode,
+  SessionEventReadDirection,
+  SessionEventReadMode,
+  SessionEventSemanticClass,
   SessionEventType,
   SessionGoal,
   SessionGoalCreatedBy,
   SessionGoalStatus,
+  SessionHumanInputRequest,
   SessionStatus,
   SessionStatusChangedPayload,
   SessionStructuredCapabilities,
   SessionTurn,
+  ServiceTurnInitiator,
+  ServiceTurnInitiatorContext,
   SessionTurnSource,
   SessionTurnStatus,
+  SubmitHumanInputResponseRequest,
+  TurnInitiator,
   ToolAuthNeededPayload,
   UpdateConnectionRequest,
   // Channel-A structured services (P4.4) — A1 payloads + A2 request/response.
@@ -327,6 +377,7 @@ export type {
   UsageEvent,
   UsageEventType,
   UserApprovalDecisionEventInput,
+  UserHumanInputResponseEventInput,
   UserMessageEventInput,
   Workspace,
   WorkspaceControlEvent,