@opengeni/sdk 0.28.2 → 0.32.1

package/dist/workspace-control-stream.d.ts

@@ -0,0 +1,12 @@
+import type { StreamSessionEventsOptions } from "./stream";
+import type { WorkspaceControlEvent } from "./types";
+export type WorkspaceControlStreamTransport = {
+    /** The server replays every durable event after the cursor before going live. */
+    openStream: (after: number, signal: AbortSignal | undefined) => Promise<ReadableStream<Uint8Array>>;
+};
+/**
+ * Reconnecting workspace invalidation stream. Control revisions are monotonic
+ * but can begin above one after the one-way migration, so unlike conversation
+ * events this stream intentionally permits sparse sequence values.
+ */
+export declare function streamWorkspaceControlEvents(transport: WorkspaceControlStreamTransport, options?: StreamSessionEventsOptions): AsyncGenerator<WorkspaceControlEvent, void, void>;

package/dist/workspace-instruction-policies.d.ts

@@ -0,0 +1,98 @@
+export type WorkspaceInstructionPolicyKind = "charter" | "policy";
+export type WorkspaceInstructionPolicyScope = "global" | "role";
+export type WorkspaceInstructionPolicyProvenanceSource = "human" | "onboarding" | "knowledge_proposal" | "legacy_import";
+export type WorkspaceInstructionPolicyDraftProvenanceSource = Exclude<WorkspaceInstructionPolicyProvenanceSource, "legacy_import">;
+export type WorkspaceInstructionPolicyActivationType = "activate" | "rollback";
+export declare function normalizeWorkspaceInstructionPolicyRoleKey(value: string): string;
+export type WorkspaceInstructionPolicyTarget = {
+    kind: WorkspaceInstructionPolicyKind;
+    scope: WorkspaceInstructionPolicyScope;
+    roleKey: string | null;
+};
+export type WorkspaceInstructionPolicyRevisionIdentity = {
+    id: string;
+    revision: number;
+    contentHash: string;
+};
+export type WorkspaceInstructionPolicyRevision = WorkspaceInstructionPolicyRevisionIdentity & WorkspaceInstructionPolicyTarget & {
+    accountId: string;
+    workspaceId: string;
+    content: string;
+    provenance: {
+        source: WorkspaceInstructionPolicyProvenanceSource;
+        sourceId: string | null;
+    };
+    supersedesRevisionId: string | null;
+    createdBySubjectId: string;
+    createdAt: string;
+};
+export type WorkspaceInstructionPolicyHead = WorkspaceInstructionPolicyTarget & {
+    workspaceId: string;
+    revisionId: string;
+    revision: number;
+    contentHash: string;
+    activationVersion: number;
+    activatedAt: string;
+};
+export type WorkspaceInstructionPolicyActivationEvent = WorkspaceInstructionPolicyTarget & {
+    id: string;
+    accountId: string;
+    workspaceId: string;
+    type: WorkspaceInstructionPolicyActivationType;
+    activationVersion: number;
+    oldRevision: WorkspaceInstructionPolicyRevisionIdentity | null;
+    newRevision: WorkspaceInstructionPolicyRevisionIdentity;
+    actorSubjectId: string;
+    reason: string;
+    createdAt: string;
+};
+export type CreateWorkspaceInstructionPolicyDraftRequest = WorkspaceInstructionPolicyTarget & {
+    content: string;
+    provenanceSource?: WorkspaceInstructionPolicyDraftProvenanceSource;
+    provenanceSourceId?: string | null;
+    supersedesRevisionId?: string | null;
+};
+export type ImportLegacyWorkspaceInstructionPolicyDraftRequest = {
+    supersedesRevisionId?: string | null;
+};
+export type WorkspaceInstructionPolicyListOptions = {
+    kind?: WorkspaceInstructionPolicyKind;
+    scope?: WorkspaceInstructionPolicyScope;
+    roleKey?: string;
+    afterRevision?: number;
+    limit?: number;
+};
+export type WorkspaceInstructionPolicyListResponse = {
+    revisions: WorkspaceInstructionPolicyRevision[];
+    activeHeads: WorkspaceInstructionPolicyHead[];
+    activationEvents: WorkspaceInstructionPolicyActivationEvent[];
+    nextAfterRevision: number | null;
+};
+export type WorkspaceInstructionPolicyDiffRequest = {
+    fromRevisionId: string;
+    toRevisionId: string;
+};
+export type WorkspaceInstructionPolicyDiffResponse = {
+    from: WorkspaceInstructionPolicyRevision;
+    to: WorkspaceInstructionPolicyRevision;
+    format: "unified";
+    diff: string;
+};
+export type ActivateWorkspaceInstructionPolicyRequest = {
+    expectedCurrentRevisionId: string | null;
+    reason: string;
+};
+export type RollbackWorkspaceInstructionPolicyRequest = {
+    targetRevisionId: string;
+    expectedCurrentRevisionId: string;
+    reason: string;
+};
+export type WorkspaceInstructionPolicyActivationResponse = {
+    head: WorkspaceInstructionPolicyHead;
+    event: WorkspaceInstructionPolicyActivationEvent;
+};
+export type WorkspaceInstructionPolicyConflictResponse = {
+    code: "WORKSPACE_INSTRUCTION_POLICY_CONFLICT";
+    message: string;
+    currentHead: WorkspaceInstructionPolicyHead | null;
+};

package/dist/workspace-state.d.ts

@@ -0,0 +1,122 @@
+import type { WorkspaceInstructionPolicyKind, WorkspaceInstructionPolicyProvenanceSource, WorkspaceInstructionPolicyScope } from "./workspace-instruction-policies";
+export type WorkspaceStateDocumentStatusCounts = {
+    queued: number;
+    indexing: number;
+    ready: number;
+    failed: number;
+};
+export type WorkspaceStateSourceKindCounts = {
+    manual_upload: number;
+    meeting_transcript: number;
+    repository: number;
+    email: number;
+    chat: number;
+    document: number;
+    web: number;
+    other: number;
+};
+export type WorkspaceStateMemoryStatusCounts = {
+    proposed: number;
+    approved: number;
+    rejected: number;
+    active: number;
+    superseded: number;
+    archived: number;
+};
+export type WorkspaceStateMemoryKindCounts = {
+    semantic: number;
+    episodic: number;
+    procedural: number;
+    decision: number;
+    preference: number;
+};
+export type WorkspaceStateGapCode = "no_document_bases" | "no_visible_documents" | "failed_documents" | "processing_documents" | "missing_topic_coverage" | "no_memory_records" | "pending_memory_review" | "partial_inventory";
+export type WorkspaceStateResponse = {
+    workspaceId: string;
+    generatedAt: string;
+    truth: {
+        current: {
+            source: "read_time_projection";
+            capturedAt: string;
+        };
+        policySnapshot: {
+            status: "not_captured";
+            reason: "workspace_instruction_policy_snapshot_not_implemented";
+        };
+    };
+    policy: {
+        authority: "workspace_instruction_policy_heads";
+        activeHeads: Array<{
+            kind: WorkspaceInstructionPolicyKind;
+            scope: WorkspaceInstructionPolicyScope;
+            roleKey: string | null;
+            revisionId: string;
+            revision: number;
+            contentHash: string;
+            activationVersion: number;
+            activatedAt: string;
+        }>;
+        activeHeadsTruncated: boolean;
+        latestRevision: {
+            kind: WorkspaceInstructionPolicyKind;
+            scope: WorkspaceInstructionPolicyScope;
+            roleKey: string | null;
+            revisionId: string;
+            revision: number;
+            contentHash: string;
+            provenanceSource: WorkspaceInstructionPolicyProvenanceSource;
+            state: "active" | "inactive";
+            createdAt: string;
+        } | null;
+        legacyRuntime: {
+            source: "workspace_override" | "deployment_default";
+            workspaceOverrideConfigured: boolean;
+        };
+        runtimeComposition: {
+            status: "not_implemented";
+        };
+    };
+    knowledge: {
+        availability: "unavailable";
+        reason: "missing_permission";
+        requiredPermission: "documents:search";
+    } | {
+        availability: "available";
+        coverage: "complete" | "partial";
+        baseCount: number;
+        bases: Array<{
+            id: string;
+            name: string;
+            visibleDocumentCount: number;
+            statusCounts: WorkspaceStateDocumentStatusCounts;
+            latestUpdatedAt: string | null;
+        }>;
+        basesTruncated: boolean;
+        inspectedVisibleDocumentCount: number;
+        documentStatusCounts: WorkspaceStateDocumentStatusCounts;
+        sourceKindCounts: WorkspaceStateSourceKindCounts;
+        topics: Array<{
+            name: string;
+            documentCount: number;
+        }>;
+        topicsTruncated: boolean;
+        latestDocumentUpdatedAt: string | null;
+        memorySample: {
+            recordCount: number;
+            sampleLimit: 100;
+            limitReached: boolean;
+            statusCounts: WorkspaceStateMemoryStatusCounts;
+            kindCounts: WorkspaceStateMemoryKindCounts;
+            preferenceAuthority: {
+                kindCountSource: "knowledge_memories_legacy_observations";
+                activeAuthority: "structured_preference_registry";
+            };
+            latestUpdatedAt: string | null;
+        };
+        gaps: Array<{
+            code: WorkspaceStateGapCode;
+            severity: "info" | "warning";
+            relatedCount: number | null;
+        }>;
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/sdk",
-  "version": "0.28.2",
+  "version": "0.32.1",
   "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": {
@@ -28,8 +28,8 @@
     "provenance": true
   },
   "scripts": {
-    "typecheck": "tsgo --noEmit",
-    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "build": "bun ../../scripts/build-typescript-package.ts",
     "prepublishOnly": "bash ../../scripts/prepublish-guard"
   },
   "engines": {

package/src/client.ts

@@ -29,6 +29,8 @@ import type {
   CodexUsageMap,
   BillingSummary,
   BillingUsageResponse,
+  InsightsRange,
+  WorkspaceInsightsResponse,
   CapabilityCatalogItem,
   CapabilityCatalogResponse,
   CapabilityInstallation,
@@ -92,6 +94,7 @@ import type {
   SwapActiveSandboxResponse,
   ListWorkspaceMembersResponse,
   PackInstallation,
+  LatencyMode,
   ReasoningEffort,
   RetainedArtifactContent,
   RetainedArtifactContentOptions,
@@ -169,6 +172,7 @@ import type {
   PtyResizeRequest,
   PtyCloseRequest,
   ToolRef,
+  TranscribeAudioResponse,
   UpdateConnectionRequest,
   UpdateKnowledgeMemoryRequest,
   UpdateScheduledTaskRequest,
@@ -210,6 +214,23 @@ import type {
   WorkspaceInstructionPolicyListResponse,
   WorkspaceInstructionPolicyRevision,
 } from "./workspace-instruction-policies";
+import type { WorkspaceStateResponse } from "./workspace-state";
+import type {
+  ActivatePreferenceRegistryRevisionRequest,
+  ChangePreferenceRegistryScopeRequest,
+  CorrectPreferenceRegistryRequest,
+  CreatePreferenceRegistryProposalRequest,
+  DeactivatePreferenceRegistryRequest,
+  PreferenceRegistryDetailResponse,
+  PreferenceRegistryFullContent,
+  PreferenceRegistryListOptions,
+  PreferenceRegistryListResponse,
+  PreferenceRegistryMutationResponse,
+  PreferenceRegistryRecord,
+  PreferenceRegistrySnapshot,
+  RejectPreferenceRegistryProposalRequest,
+  SupersedePreferenceRegistryRequest,
+} from "./preference-registry";
 import {
   OPENGENI_API_CONTRACT_HEADER,
   OPENGENI_API_CONTRACT_REVISION,
@@ -248,7 +269,7 @@ export type OpenGeniClientOptions = {
   fetch?: FetchLike;
 };
 
-/** Per-request cancellation for identity-scoped, side-effect-free reads. */
+/** Per-request cancellation for operations whose caller owns an AbortSignal. */
 export type OpenGeniRequestOptions = {
   signal?: AbortSignal | undefined;
 };
@@ -261,6 +282,7 @@ export type SendMessageInput = {
   tools?: ToolRef[];
   model?: string;
   reasoningEffort?: ReasoningEffort;
+  latencyMode?: LatencyMode;
   clientEventId?: string;
   controlEtag?: string;
   expectedDraftRevision?: number;
@@ -274,6 +296,13 @@ export type SteerMessageResult = {
   turn: SessionTurn;
 };
 
+export type TranscribeAudioInput = {
+  audio: Blob | File | Uint8Array;
+  mimeType: string;
+  durationSeconds?: number | undefined;
+  signal?: AbortSignal | undefined;
+};
+
 /**
  * Typed client for the OpenGeni public API. Framework-agnostic: only needs
  * WHATWG `fetch` + streams, so it runs in Node 18+, Bun, Deno, browsers, and
@@ -293,6 +322,60 @@ export class OpenGeniClient {
 
   // --- Session lifecycle ---------------------------------------------------
 
+  /** Upload one ephemeral browser recording. This method never retries. */
+  async transcribeAudio(
+    workspaceId: string,
+    input: TranscribeAudioInput,
+  ): Promise<TranscribeAudioResponse> {
+    const correlationId = crypto.randomUUID();
+    const form = new FormData();
+    const filename = filenameForAudioMimeType(input.mimeType);
+    const audio =
+      input.audio instanceof File
+        ? input.audio
+        : input.audio instanceof Uint8Array
+          ? new File([Uint8Array.from(input.audio)], filename, { type: input.mimeType })
+          : new File([input.audio], filename, { type: input.mimeType || input.audio.type });
+    form.append("audio", audio, filename);
+    form.append("mimeType", input.mimeType);
+    if (input.durationSeconds !== undefined) {
+      form.append("durationSeconds", String(input.durationSeconds));
+    }
+    let response: Response;
+    try {
+      response = await this.fetchImpl(this.url(`/v1/workspaces/${workspaceId}/transcriptions`), {
+        method: "POST",
+        headers: { ...this.headers(correlationId), Accept: "application/json" },
+        body: form,
+        ...(input.signal ? { signal: input.signal } : {}),
+      });
+    } catch (error) {
+      if (input.signal?.aborted) throw error;
+      throw mutationTransportError(correlationId);
+    }
+    assertApiContractResponse(response);
+    if (!response.ok) throw await apiErrorFromResponse(response, { method: "POST", correlationId });
+    await assertJsonResponse(response, { method: "POST", correlationId });
+    let body: unknown;
+    try {
+      body = await response.json();
+    } catch {
+      throw new OpenGeniApiError(response.status, "Invalid transcription response.", {
+        code: "invalid_response",
+        mutation: true,
+        correlationId,
+      });
+    }
+    if (!isTranscribeAudioResponse(body)) {
+      throw new OpenGeniApiError(response.status, "Invalid transcription response.", {
+        code: "invalid_response",
+        mutation: true,
+        correlationId,
+      });
+    }
+    return body;
+  }
+
   async createSession(
     workspaceId: string,
     request: CreateSessionRequest,
@@ -482,7 +565,7 @@ export class OpenGeniClient {
   async listTurns(
     workspaceId: string,
     sessionId: string,
-    options: { limit?: number } = {},
+    options: { limit?: number; latestStarted?: boolean } = {},
   ): Promise<SessionTurn[]> {
     return await this.requestJson<SessionTurn[]>(
       "GET",
@@ -490,10 +573,17 @@ export class OpenGeniClient {
       undefined,
       {
         ...(options.limit !== undefined ? { limit: String(options.limit) } : {}),
+        ...(options.latestStarted ? { latestStarted: "1" } : {}),
       },
     );
   }
 
+  /** Newest turn that durably emitted `turn.started`, or null before any admission. */
+  async getLatestStartedTurn(workspaceId: string, sessionId: string): Promise<SessionTurn | null> {
+    const turns = await this.listTurns(workspaceId, sessionId, { latestStarted: true });
+    return turns[0] ?? null;
+  }
+
   // --- Bring-your-own-compute: Machines dashboard + metrics (M10) ------------
 
   /**
@@ -1623,6 +1713,14 @@ export class OpenGeniClient {
     return await this.requestJson<Workspace>("GET", `/v1/workspaces/${workspaceId}`);
   }
 
+  /** Read-time, secret-safe inventory of policy heads and visible workspace knowledge. */
+  async getWorkspaceState(workspaceId: string): Promise<WorkspaceStateResponse> {
+    return await this.requestJson<WorkspaceStateResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/workspace-state`,
+    );
+  }
+
   async updateWorkspace(workspaceId: string, request: UpdateWorkspaceRequest): Promise<Workspace> {
     return await this.requestJson<Workspace>("PATCH", `/v1/workspaces/${workspaceId}`, request);
   }
@@ -1717,6 +1815,132 @@ export class OpenGeniClient {
     );
   }
 
+  async listPreferenceRegistry(
+    workspaceId: string,
+    options: PreferenceRegistryListOptions = {},
+  ): Promise<PreferenceRegistryListResponse> {
+    const params = new URLSearchParams();
+    if (options.scope) params.set("scope", options.scope);
+    if (options.status) params.set("status", options.status);
+    if (options.limit !== undefined) params.set("limit", String(options.limit));
+    const query = params.toString();
+    return await this.requestJson<PreferenceRegistryListResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/preferences${query ? `?${query}` : ""}`,
+    );
+  }
+
+  async getPreferenceRegistry(
+    workspaceId: string,
+    preferenceId: string,
+  ): Promise<PreferenceRegistryDetailResponse> {
+    return await this.requestJson<PreferenceRegistryDetailResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}`,
+    );
+  }
+
+  async createPreferenceRegistryProposal(
+    workspaceId: string,
+    request: CreatePreferenceRegistryProposalRequest,
+  ): Promise<PreferenceRegistryRecord> {
+    return await this.requestJson<PreferenceRegistryRecord>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/proposals`,
+      request,
+    );
+  }
+
+  async activatePreferenceRegistryRevision(
+    workspaceId: string,
+    preferenceId: string,
+    request: ActivatePreferenceRegistryRevisionRequest,
+  ): Promise<PreferenceRegistryMutationResponse> {
+    return await this.requestJson<PreferenceRegistryMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/activate`,
+      request,
+    );
+  }
+
+  async correctPreferenceRegistry(
+    workspaceId: string,
+    preferenceId: string,
+    request: CorrectPreferenceRegistryRequest,
+  ): Promise<PreferenceRegistryMutationResponse> {
+    return await this.requestJson<PreferenceRegistryMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/correct`,
+      request,
+    );
+  }
+
+  async changePreferenceRegistryScope(
+    workspaceId: string,
+    preferenceId: string,
+    request: ChangePreferenceRegistryScopeRequest,
+  ): Promise<PreferenceRegistryMutationResponse> {
+    return await this.requestJson<PreferenceRegistryMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/scope`,
+      request,
+    );
+  }
+
+  async deactivatePreferenceRegistry(
+    workspaceId: string,
+    preferenceId: string,
+    request: DeactivatePreferenceRegistryRequest,
+  ): Promise<PreferenceRegistryMutationResponse> {
+    return await this.requestJson<PreferenceRegistryMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/deactivate`,
+      request,
+    );
+  }
+
+  async supersedePreferenceRegistry(
+    workspaceId: string,
+    preferenceId: string,
+    request: SupersedePreferenceRegistryRequest,
+  ): Promise<PreferenceRegistryMutationResponse> {
+    return await this.requestJson<PreferenceRegistryMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/supersede`,
+      request,
+    );
+  }
+
+  async rejectPreferenceRegistryProposal(
+    workspaceId: string,
+    preferenceId: string,
+    request: RejectPreferenceRegistryProposalRequest,
+  ): Promise<PreferenceRegistryMutationResponse> {
+    return await this.requestJson<PreferenceRegistryMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/reject`,
+      request,
+    );
+  }
+
+  async getPreferenceRegistrySummary(workspaceId: string): Promise<PreferenceRegistrySnapshot> {
+    return await this.requestJson<PreferenceRegistrySnapshot>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/preferences/summary`,
+    );
+  }
+
+  async getPreferenceRegistryFullContent(
+    workspaceId: string,
+    retrievalHandle: string,
+  ): Promise<PreferenceRegistryFullContent> {
+    return await this.requestJson<PreferenceRegistryFullContent>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/full-content`,
+      { retrievalHandle },
+    );
+  }
+
   /**
    * Delete a workspace and everything in it. Refused (409) for the account's
    * only workspace and while it still has a running session. Irreversible.
@@ -2627,11 +2851,14 @@ export class OpenGeniClient {
   async startConnectionOAuth(
     workspaceId: string,
     request: OAuthStartRequest,
+    options: OpenGeniRequestOptions = {},
   ): Promise<OAuthStartResponse> {
     return await this.requestJson<OAuthStartResponse>(
       "POST",
       `/v1/workspaces/${workspaceId}/connections/oauth/start`,
       request,
+      {},
+      options,
     );
   }
 
@@ -2734,6 +2961,26 @@ export class OpenGeniClient {
     });
   }
 
+  async getWorkspaceInsights(
+    workspaceId: string,
+    options: {
+      range?: InsightsRange;
+      provider?: string;
+      model?: string;
+    } = {},
+  ): Promise<WorkspaceInsightsResponse> {
+    return await this.requestJson<WorkspaceInsightsResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/insights`,
+      undefined,
+      {
+        range: options.range ?? "week",
+        ...(options.provider !== undefined ? { provider: options.provider } : {}),
+        ...(options.model !== undefined ? { model: options.model } : {}),
+      },
+    );
+  }
+
   async getBillingEntitlements(
     options: { accountId?: string } = {},
   ): Promise<BillingEntitlementsResponse> {
@@ -2993,6 +3240,36 @@ function assertApiContractResponse(response: Response): void {
   }
 }
 
+function isTranscribeAudioResponse(value: unknown): value is TranscribeAudioResponse {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  return (
+    typeof record.text === "string" &&
+    Array.isArray(record.languages) &&
+    record.languages.every((language) => typeof language === "string")
+  );
+}
+
+function filenameForAudioMimeType(mimeType: string): string {
+  const bare = mimeType.trim().toLowerCase().split(";")[0] ?? "audio/webm";
+  switch (bare) {
+    case "audio/mp4":
+    case "audio/m4a":
+      return "audio.mp4";
+    case "audio/ogg":
+      return "audio.ogg";
+    case "audio/mpeg":
+    case "audio/mp3":
+      return "audio.mp3";
+    case "audio/wav":
+    case "audio/x-wav":
+      return "audio.wav";
+    case "audio/webm":
+    default:
+      return "audio.webm";
+  }
+}
+
 const API_ERROR_MAX_BYTES = 16 * 1024;
 
 type ApiErrorRequestContext = {