@opengeni/sdk 0.52.1 → 1.0.0

package/src/codex-realtime-v3.ts

@@ -35,9 +35,10 @@ export const CODEX_REALTIME_V3_PENDING_MAX_ENTRIES = 256;
 export const CODEX_REALTIME_V3_PENDING_MAX_BYTES = 16 * 1024 * 1024;
 const REALTIME_DELEGATION_TRANSCRIPT_MAX_BYTES = 65_536;
 const REALTIME_DELEGATION_INPUT_MAX_BYTES = 65_536;
+const REALTIME_MODEL_CONTEXT_MAX_CHARACTERS = 32_768;
 
 export type CodexRealtimeV3BridgeFatal = {
-  code: "pending_overflow";
+  code: "pending_overflow" | "replay_journal_failed";
   message: string;
 };
 
@@ -72,6 +73,19 @@ export type CodexRealtimeV3BridgeOptions = {
   >;
   sync(request: SyncSessionRealtimeLedgerRequest): Promise<SyncSessionRealtimeLedgerResponse>;
   randomUUID?: (() => string) | undefined;
+  /** Model-visible application context captured once for each durable message-bearing entry. */
+  getModelContext?: (() => string | undefined) | undefined;
+  /** Controller-lifetime delegation identities shared across provider connection rotations. */
+  acceptedDelegationItemIds?: Set<string> | undefined;
+  /** Unsynced delegation snapshots retained exactly across provider connection rotations. */
+  pendingDelegations?: Map<string, SessionRealtimeInboundEntry> | undefined;
+  /** Persist exact delegation replay state before it becomes browser-reload-sensitive. */
+  onDelegationReplayStateChange?:
+    | ((state: {
+        acceptedDelegationItemIds: ReadonlySet<string>;
+        pendingDelegations: ReadonlyMap<string, SessionRealtimeInboundEntry>;
+      }) => void)
+    | undefined;
   /** The controller installs its activation FIFO first, then enables this listener synchronously. */
   listen?: boolean | undefined;
   onSnapshot?: ((snapshot: CodexRealtimeV3BridgeSnapshot) => void) | undefined;
@@ -125,9 +139,32 @@ export function createCodexRealtimeV3Bridge(
   const clientReceivedSequences = new Set<number>();
   const sentSequences = new Set<number>();
   const finalizedTurnIds = new Set<string>();
+  const acceptedDelegationItemIds = options.acceptedDelegationItemIds ?? new Set<string>();
+  const pendingDelegations = options.pendingDelegations ?? new Map();
+  const locallyQueuedDelegationItemIds = new Set<string>();
   let transcriptSinceDelegation: FinalizedTranscript[] = [];
-  let pendingDelegationUserTranscript: { delegationItemId: string; text: string } | null = null;
+  let pendingDelegationUserTranscript: {
+    delegationItemId: string;
+    text: string;
+  } | null = null;
   const randomUUID = options.randomUUID ?? defaultRandomUUID;
+  const currentModelContext = (): string | undefined => {
+    let context: string | undefined;
+    try {
+      context = options.getModelContext?.()?.trim();
+    } catch {
+      lastError =
+        "Realtime model context callback failed; the provider message continued without application context";
+      return undefined;
+    }
+    if (!context) return undefined;
+    if (context.length > REALTIME_MODEL_CONTEXT_MAX_CHARACTERS) {
+      lastError =
+        "Realtime model context exceeded the 32768-character limit; the provider message continued without application context";
+      return undefined;
+    }
+    return context;
+  };
 
   const snapshot = (): CodexRealtimeV3BridgeSnapshot => ({
     connectionId: options.connectionId,
@@ -148,9 +185,9 @@ export function createCodexRealtimeV3Bridge(
   });
   const publish = (): void => options.onSnapshot?.(snapshot());
 
-  const triggerFatal = (message: string): void => {
+  const triggerFatalCode = (code: CodexRealtimeV3BridgeFatal["code"], message: string): void => {
     if (closed || fatal) return;
-    fatal = { code: "pending_overflow", message };
+    fatal = { code, message };
     lastError = message;
     publish();
     try {
@@ -161,6 +198,10 @@ export function createCodexRealtimeV3Bridge(
     }
   };
 
+  const triggerFatal = (message: string): void => {
+    triggerFatalCode("pending_overflow", message);
+  };
+
   const enqueue = (entry: SessionRealtimeInboundEntry): boolean => {
     if (closed || sealed || fatal) return false;
     const bytes = utf8ByteLength(JSON.stringify(entry));
@@ -177,6 +218,14 @@ export function createCodexRealtimeV3Bridge(
     return true;
   };
 
+  // Same-browser reload reconstructs this exact map from the persisted owner
+  // journal. Queue those first-frozen calls before listening to the replacement
+  // provider connection; startup proof or a duplicate call drives the normal
+  // flush path without resampling application context.
+  for (const [delegationItemId, entry] of pendingDelegations) {
+    if (enqueue(entry)) locallyQueuedDelegationItemIds.add(delegationItemId);
+  }
+
   const hasWork = (): boolean =>
     pendingInbound.length > 0 ||
     (!providerStartedAccepted && providerStarted !== undefined) ||
@@ -213,7 +262,46 @@ export function createCodexRealtimeV3Bridge(
         throw error;
       }
 
+      const acceptedAfterSync = new Set(acceptedDelegationItemIds);
+      const pendingAfterSync = new Map(pendingDelegations);
+      let delegationReplayChanged = false;
+      for (const item of batch) {
+        if (item.entry.kind === "delegation_call" && item.entry.delegationItemId) {
+          delegationReplayChanged = true;
+          acceptedAfterSync.add(item.entry.delegationItemId);
+          if (pendingAfterSync.get(item.entry.delegationItemId) === item.entry) {
+            pendingAfterSync.delete(item.entry.delegationItemId);
+          }
+        }
+      }
+      if (delegationReplayChanged) {
+        try {
+          options.onDelegationReplayStateChange?.({
+            acceptedDelegationItemIds: acceptedAfterSync,
+            pendingDelegations: pendingAfterSync,
+          });
+        } catch (error) {
+          // The server may already have admitted this exact batch. Keep it
+          // queued with the original operation identity and stop this bridge.
+          // Recovery can safely replay it because the prior pending journal
+          // state remains authoritative until the accepted transition writes.
+          pendingInbound = [...batch, ...pendingInbound];
+          triggerFatalCode(
+            "replay_journal_failed",
+            `Codex realtime delegation replay journal failed: ${safeError(error)}`,
+          );
+          return;
+        }
+      }
+
       for (const item of batch) {
+        if (item.entry.kind === "delegation_call" && item.entry.delegationItemId) {
+          acceptedDelegationItemIds.add(item.entry.delegationItemId);
+          if (pendingDelegations.get(item.entry.delegationItemId) === item.entry) {
+            pendingDelegations.delete(item.entry.delegationItemId);
+          }
+          locallyQueuedDelegationItemIds.delete(item.entry.delegationItemId);
+        }
         pendingInboundCount -= 1;
         pendingInboundBytes -= item.bytes;
       }
@@ -345,31 +433,67 @@ export function createCodexRealtimeV3Bridge(
       // These events are provider UI deltas. `turn.done` is the single
       // authoritative finalized transcript persisted below.
     } else if (event.type === "delegation.created") {
-      activeDelegationId = event.delegationItemId;
-      const transcript = delegationTranscript(transcriptSinceDelegation, event.inputTranscript);
-      const coveredTurnIds = transcriptSinceDelegation.map((entry) => entry.turnId);
-      durable = enqueue({
-        operationId: randomUUID(),
-        kind: "delegation_call",
-        providerEventId: event.providerEventId,
-        delegationItemId: event.delegationItemId,
-        text: renderRealtimeDelegationInput(event.inputTranscript, transcript),
-        payload: {
-          offsetMs: event.offsetMs,
-          inputTranscript: event.inputTranscript,
-          transcriptFenceTurnIds: coveredTurnIds,
-        },
-      });
-      if (durable) {
-        const alreadyFinalized = transcriptSinceDelegation.some(
-          (entry) =>
-            entry.role === "user" &&
-            normalizedTranscript(entry.text) === normalizedTranscript(event.inputTranscript),
-        );
-        pendingDelegationUserTranscript = alreadyFinalized
-          ? null
-          : { delegationItemId: event.delegationItemId, text: event.inputTranscript };
-        transcriptSinceDelegation = [];
+      if (acceptedDelegationItemIds.has(event.delegationItemId)) {
+        ignoredEventCount += 1;
+        lastIgnoredEventType = event.type;
+      } else if (locallyQueuedDelegationItemIds.has(event.delegationItemId)) {
+        ignoredEventCount += 1;
+        lastIgnoredEventType = event.type;
+        durable = true;
+      } else {
+        let entry = pendingDelegations.get(event.delegationItemId);
+        if (!entry) {
+          const transcript = delegationTranscript(transcriptSinceDelegation, event.inputTranscript);
+          const coveredTurnIds = transcriptSinceDelegation.map((item) => item.turnId);
+          const modelContext = currentModelContext();
+          entry = {
+            operationId: randomUUID(),
+            kind: "delegation_call",
+            providerEventId: event.providerEventId,
+            delegationItemId: event.delegationItemId,
+            text: renderRealtimeDelegationInput(event.inputTranscript, transcript),
+            payload: {
+              offsetMs: event.offsetMs,
+              inputTranscript: event.inputTranscript,
+              transcriptFenceTurnIds: coveredTurnIds,
+            },
+            ...(modelContext ? { modelContext } : {}),
+          };
+          pendingDelegations.set(event.delegationItemId, entry);
+        }
+        try {
+          options.onDelegationReplayStateChange?.({
+            acceptedDelegationItemIds,
+            pendingDelegations,
+          });
+        } catch (error) {
+          triggerFatalCode(
+            "replay_journal_failed",
+            `Codex realtime delegation replay journal failed: ${safeError(error)}`,
+          );
+          return Promise.resolve();
+        }
+        durable = enqueue(entry);
+        if (durable) {
+          locallyQueuedDelegationItemIds.add(event.delegationItemId);
+          activeDelegationId = event.delegationItemId;
+          const frozenInputTranscript =
+            typeof entry.payload.inputTranscript === "string"
+              ? entry.payload.inputTranscript
+              : event.inputTranscript;
+          const alreadyFinalized = transcriptSinceDelegation.some(
+            (item) =>
+              item.role === "user" &&
+              normalizedTranscript(item.text) === normalizedTranscript(frozenInputTranscript),
+          );
+          pendingDelegationUserTranscript = alreadyFinalized
+            ? null
+            : {
+                delegationItemId: event.delegationItemId,
+                text: frozenInputTranscript,
+              };
+          transcriptSinceDelegation = [];
+        }
       }
     } else if (event.type === "output_audio.delta") {
       speaking = true;
@@ -383,7 +507,9 @@ export function createCodexRealtimeV3Bridge(
             normalizedTranscript(pendingDelegationUserTranscript.text)
             ? pendingDelegationUserTranscript.delegationItemId
             : null;
-        durable = enqueue(finalTranscript(randomUUID, event, coveredByDelegationItemId));
+        durable = enqueue(
+          finalTranscript(randomUUID, event, coveredByDelegationItemId, currentModelContext()),
+        );
         if (durable) {
           finalizedTurnIds.add(event.turnId);
           if (coveredByDelegationItemId) {
@@ -446,6 +572,7 @@ function finalTranscript(
   randomUUID: () => string,
   event: Extract<CodexRealtimeV3Event, { type: "turn.done" }>,
   coveredByDelegationItemId: string | null,
+  modelContext: string | undefined,
 ): SessionRealtimeInboundEntry {
   return {
     operationId: randomUUID(),
@@ -456,6 +583,7 @@ function finalTranscript(
       turnId: event.turnId,
       ...(coveredByDelegationItemId ? { coveredByDelegationItemId } : {}),
     },
+    ...(modelContext ? { modelContext } : {}),
   };
 }
 
@@ -539,7 +667,10 @@ function sendOutbound(events: RTCDataChannel, entry: SessionRealtimeLedgerEntry)
           text,
           channel: payloadChannel ?? "speakable",
         })
-      : encodeCodexRealtimeV3SessionContextAppend({ text, channel: payloadChannel });
+      : encodeCodexRealtimeV3SessionContextAppend({
+          text,
+          channel: payloadChannel,
+        });
   for (const message of messages) events.send(JSON.stringify(message));
 }
 

package/src/codex-realtime.ts

@@ -261,7 +261,7 @@ export async function startCodexRealtimeWebrtc(
     );
     throwIfAborted(options.signal);
     if (answer.version !== "v3" || answer.model !== "gpt-live-1-boulder-alpha" || !answer.sdp) {
-      throw new Error("OpenGeni returned an incompatible Codex realtime answer");
+      throw new Error("Opengeni returned an incompatible Codex realtime answer");
     }
     await peerConnection.setRemoteDescription({
       type: "answer",

package/src/company-brain.ts

@@ -0,0 +1,59 @@
+import type {
+  CompanyBrainContextReceiptPage as ContractCompanyBrainContextReceiptPage,
+  CompanyBrainKnowledgeProposalPage as ContractCompanyBrainKnowledgeProposalPage,
+  CompanyBrainOkfPackage as ContractCompanyBrainOkfPackage,
+} from "@opengeni/contracts";
+
+export type CompanyBrainOkfPackage = ContractCompanyBrainOkfPackage;
+export type CompanyBrainContextReceiptPage = ContractCompanyBrainContextReceiptPage;
+export type CompanyBrainKnowledgeProposalPage = ContractCompanyBrainKnowledgeProposalPage;
+
+export type CompanyBrainContextReceiptListOptions = {
+  attemptId?: string;
+  cursor?: string;
+  limit?: number;
+};
+
+export type CompanyBrainKnowledgeProposalListOptions = {
+  limit?: number;
+};
+
+export type CompanyBrainInspectorTransport = {
+  requestJson<T>(method: string, path: string, body?: unknown): Promise<T>;
+};
+
+function inspectorPath(workspaceId: string, suffix: string): string {
+  return `/v1/workspaces/${workspaceId}/company-brain/${suffix}`;
+}
+
+export function listCompanyBrainContextReceipts(
+  client: CompanyBrainInspectorTransport,
+  workspaceId: string,
+  options: CompanyBrainContextReceiptListOptions = {},
+): Promise<CompanyBrainContextReceiptPage> {
+  const params = new URLSearchParams();
+  if (options.attemptId) params.set("attemptId", options.attemptId);
+  if (options.cursor) params.set("cursor", options.cursor);
+  if (options.limit !== undefined) params.set("limit", String(options.limit));
+  const query = params.toString();
+  return client.requestJson(
+    "GET",
+    `${inspectorPath(workspaceId, "context-receipts")}${query ? `?${query}` : ""}`,
+  );
+}
+
+export function listCompanyBrainKnowledgeProposals(
+  client: CompanyBrainInspectorTransport,
+  workspaceId: string,
+  options: CompanyBrainKnowledgeProposalListOptions = {},
+): Promise<CompanyBrainKnowledgeProposalPage> {
+  const query =
+    options.limit === undefined ? "" : `?limit=${encodeURIComponent(String(options.limit))}`;
+  return client.requestJson("GET", `${inspectorPath(workspaceId, "knowledge-proposals")}${query}`);
+}
+
+export type CompanyBrainOkfDownload = {
+  content: string;
+  contentType: string;
+  filename: string;
+};

package/src/company-profile.ts

@@ -21,7 +21,10 @@ export type CompanyProfileRevision = CompanyProfileRevisionIdentity & {
   accountId: string;
   intent: "active" | "proposal";
   profile: CompanyProfileContent;
-  provenance: { source: "human" | "durable_learning" | "migration"; sourceId: string | null };
+  provenance: {
+    source: "human" | "agent_admin" | "durable_learning" | "migration";
+    sourceId: string | null;
+  };
   supersedesRevisionId: string | null;
   createdBySubjectId: string;
   createdAt: string;
@@ -79,6 +82,19 @@ export type CompanyProfileMutationResponse = {
   head: CompanyProfileHead | null;
   event: CompanyProfileActivationEvent | null;
 };
+export type CompanyProfileAgentPolicyMode = "off" | "suggest" | "automatic";
+export type CompanyProfileAgentPolicy = {
+  organizationId: string;
+  mode: CompanyProfileAgentPolicyMode;
+  version: number;
+  updatedAt: string;
+  changed?: boolean;
+};
+export type UpdateCompanyProfileAgentPolicyRequest = {
+  mode: CompanyProfileAgentPolicyMode;
+  expectedVersion: number;
+  operationId: string;
+};
 export type CompanyProfileDiffRequest = { fromRevisionId: string; toRevisionId: string };
 export type CompanyProfileDiffResponse = {
   from: CompanyProfileRevision;

package/src/core.ts

@@ -1,6 +1,22 @@
-export { OpenGeniClient as OpenGeniCoreClient } from "./client";
+/** Backward-compatible non-artifact client surface. */
+export { OpenGeniDocumentAuthorityClient as OpenGeniCoreClient } from "./document-authority-client";
+export {
+  OpenGeniToolCallError,
+  OpenGeniToolReapprovalRequiredError,
+  OpenGeniToolsClient,
+} from "./tools";
+export type {
+  OpenGeniGeneratedTools,
+  OpenGeniDynamicToolNode,
+  OpenGeniToolCallOptions,
+  OpenGeniToolFunction,
+  OpenGeniToolsFacade,
+  OpenGeniWorkspaceTools,
+} from "./tools";
 export type {
   FetchLike,
+  FetchResponse,
+  GetSessionOptions,
   OpenGeniClientOptions,
   OpenGeniRequestOptions,
   SendMessageInput,
@@ -11,9 +27,15 @@ export type {
 export {
   OpenGeniApiContractMismatchError,
   OpenGeniApiError,
+  OpenGeniSetupError,
+  OpenGeniSecureContextRequiredError,
   OpenGeniSessionListCursorError,
   OpenGeniStreamError,
+  formatErrorMessage,
   isRetryableStreamError,
 } from "./errors";
+export type { OpenGeniSecureContextRequiredReason } from "./errors";
+export { parseDeprecationNotice } from "./deprecation";
+export type { OpenGeniDeprecationHandler, OpenGeniDeprecationNotice } from "./deprecation";
 export { resolveWorkspaceVoiceInputEnabled } from "./transcription";
 export { OPENGENI_API_CONTRACT_HEADER, OPENGENI_API_CONTRACT_REVISION } from "./types";

package/src/deprecation.ts

@@ -0,0 +1,149 @@
+/**
+ * Deprecation notices advertised by the OpenGeni API.
+ *
+ * Per the public API compatibility policy, a route whose behaviour is scheduled
+ * for removal answers with the standard `Deprecation` (RFC 9745) and `Sunset`
+ * (RFC 8594) headers plus `Link: <notes>; rel="deprecation"`. The client
+ * surfaces them through `OpenGeniClientOptions.onDeprecation`, or by default
+ * as a one-time `console.warn` per route, so an integrator pinned to an older
+ * SDK learns about a removal well before it happens.
+ */
+
+export type OpenGeniDeprecationNotice = {
+  /** Request method, upper case. */
+  method: string;
+  /** Request path with ids collapsed (`/v1/workspaces/:id/...`), stable per route. */
+  route: string;
+  /** Exact request path. */
+  path: string;
+  /** When the deprecation was announced, if the header carried a date. */
+  deprecatedAt: Date | null;
+  /** Earliest removal on the server, if advertised. */
+  sunset: Date | null;
+  /** Migration notes (`rel="deprecation"`), if advertised. */
+  link: string | null;
+  /** Replacement (`rel="successor-version"`), if advertised. */
+  successor: string | null;
+};
+
+/** `false` silences notices; a function receives each route's notice once per client. */
+export type OpenGeniDeprecationHandler = (notice: OpenGeniDeprecationNotice) => void;
+
+type HeaderBag = { get(name: string): string | null };
+
+const ID_SEGMENT =
+  /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|\d+|[A-Za-z0-9_-]{20,})$/i;
+
+function routeKey(path: string): string {
+  return path
+    .split("/")
+    .map((segment) => (ID_SEGMENT.test(segment) ? ":id" : segment))
+    .join("/");
+}
+
+function parseDeprecationDate(value: string): Date | null {
+  const trimmed = value.trim();
+  // RFC 9745 structured date `@<unix seconds>`; older drafts used `true` or an HTTP-date.
+  const structured = /^@(-?\d+)$/.exec(trimmed);
+  if (structured) return new Date(Number(structured[1]) * 1000);
+  const parsed = Date.parse(trimmed);
+  return Number.isNaN(parsed) ? null : new Date(parsed);
+}
+
+function parseLinks(value: string | null): Map<string, string> {
+  const links = new Map<string, string>();
+  if (!value) return links;
+  for (const match of value.matchAll(/<([^>]*)>\s*((?:;\s*[^;,]+)*)/g)) {
+    const rel = /;\s*rel="?([^";,]+)"?/i.exec(match[2] ?? "")?.[1];
+    if (!rel) continue;
+    for (const name of rel.toLowerCase().split(/\s+/)) {
+      if (!links.has(name)) links.set(name, match[1]!);
+    }
+  }
+  return links;
+}
+
+/** Read a deprecation notice from response headers; `null` when none is advertised. */
+export function parseDeprecationNotice(
+  method: string,
+  url: string,
+  headers: HeaderBag,
+): OpenGeniDeprecationNotice | null {
+  const deprecation = headers.get("deprecation");
+  const sunsetHeader = headers.get("sunset");
+  if (!deprecation && !sunsetHeader) return null;
+  let path = url;
+  try {
+    path = new URL(url, "http://opengeni.invalid").pathname;
+  } catch {
+    // Keep the raw value; the notice is advisory.
+  }
+  const sunset = sunsetHeader ? Date.parse(sunsetHeader) : Number.NaN;
+  const links = parseLinks(headers.get("link"));
+  return {
+    method: method.toUpperCase(),
+    route: routeKey(path),
+    path,
+    deprecatedAt: deprecation ? parseDeprecationDate(deprecation) : null,
+    sunset: Number.isNaN(sunset) ? null : new Date(sunset),
+    link: links.get("deprecation") ?? links.get("sunset") ?? null,
+    successor: links.get("successor-version") ?? null,
+  };
+}
+
+const warnedRoutes = new Set<string>();
+
+/** The default handler: one `console.warn` per route per process. */
+export function warnDeprecationOnce(notice: OpenGeniDeprecationNotice): void {
+  const key = `${notice.method} ${notice.route}`;
+  if (warnedRoutes.has(key)) return;
+  warnedRoutes.add(key);
+  const sunset = notice.sunset ? ` and will be removed after ${notice.sunset.toISOString()}` : "";
+  const notes = notice.link ? ` Migration notes: ${notice.link}.` : "";
+  console.warn(
+    `[@opengeni/sdk] ${key} is deprecated${sunset}.${notes} Upgrade @opengeni/sdk, or pass onDeprecation to handle this notice.`,
+  );
+}
+
+type FetchFunction<R extends { headers: HeaderBag }> = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<R>;
+
+/**
+ * Wrap a fetch implementation so every response is inspected for a deprecation
+ * notice. The handler runs at most once per route for this wrapper and never
+ * affects the request: a throwing handler is swallowed.
+ */
+export function withDeprecationNotices<R extends { headers: HeaderBag }>(
+  fetchImpl: FetchFunction<R>,
+  handler: OpenGeniDeprecationHandler | false | undefined,
+): FetchFunction<R> {
+  if (handler === false) return fetchImpl;
+  const notify = handler ?? warnDeprecationOnce;
+  const seen = new Set<string>();
+  return async (input, init) => {
+    const response = await fetchImpl(input, init);
+    try {
+      const headers = response.headers;
+      if (headers && (headers.get("deprecation") || headers.get("sunset"))) {
+        const method =
+          init?.method ??
+          (typeof Request !== "undefined" && input instanceof Request ? input.method : "GET");
+        const url =
+          typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+        const notice = parseDeprecationNotice(method, url, headers);
+        if (notice) {
+          const key = `${notice.method} ${notice.route}`;
+          if (!seen.has(key)) {
+            seen.add(key);
+            notify(notice);
+          }
+        }
+      }
+    } catch {
+      // Deprecation notices are advisory and must never fail a request.
+    }
+    return response;
+  };
+}

package/src/desktop.ts

@@ -71,13 +71,23 @@ export interface DesktopRfbLike {
     type: "connect" | "disconnect" | "securityfailure",
     cb: (e?: unknown) => void,
   ) => void;
+  /** Send clipboard text over the already-open RFB connection. */
+  clipboardPasteFrom?(text: string): void;
+  /** Send one RFB key event. A missing `down` emits a complete key press. */
+  sendKey?(keysym: number, code: string, down?: boolean): void;
+  /** Focus or release the RFB keyboard sink without reconnecting. */
+  focus?(options?: FocusOptions): void;
+  blur?(): void;
   disconnect(): void;
 }
 
 export type DesktopRfbFactory = (
   target: HTMLElement,
   url: string,
-  opts: { credentials?: { password?: string | undefined } | undefined },
+  opts: {
+    credentials?: { password?: string | undefined } | undefined;
+    wsProtocols?: string[] | undefined;
+  },
 ) => DesktopRfbLike;
 
 export type DesktopConnectionState =