@opengeni/sdk 3.1.0 → 3.3.2-canary.1

package/src/company-profile.ts

@@ -82,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

@@ -13,9 +13,11 @@ export type {
 export {
   OpenGeniApiContractMismatchError,
   OpenGeniApiError,
+  OpenGeniSecureContextRequiredError,
   OpenGeniSessionListCursorError,
   OpenGeniStreamError,
   isRetryableStreamError,
 } from "./errors";
+export type { OpenGeniSecureContextRequiredReason } from "./errors";
 export { resolveWorkspaceVoiceInputEnabled } from "./transcription";
 export { OPENGENI_API_CONTRACT_HEADER, OPENGENI_API_CONTRACT_REVISION } from "./types";

package/src/errors.ts

@@ -49,6 +49,29 @@ export class OpenGeniApiError extends Error {
   }
 }
 
+export type OpenGeniSecureContextRequiredReason = "insecure_context" | "web_crypto_unavailable";
+
+/**
+ * A browser operation requires secure-context-only platform capabilities.
+ * Callers may key UI behavior on the stable `secure_context_required` code;
+ * `reason` exists only to keep the human guidance truthful.
+ */
+export class OpenGeniSecureContextRequiredError extends Error {
+  readonly code = "secure_context_required" as const;
+  readonly retryable = false;
+  readonly reason: OpenGeniSecureContextRequiredReason;
+
+  constructor(reason: OpenGeniSecureContextRequiredReason) {
+    super(
+      reason === "insecure_context"
+        ? "Couldn’t attach this file because OpenGeni is open over HTTP. Attachments require a secure HTTPS connection. Open the secure site or configure HTTPS for this deployment."
+        : "Couldn’t attach this file because secure browser cryptography is unavailable. Attachments require HTTPS and Web Crypto support. Open a secure site in a supported browser or configure HTTPS for this deployment.",
+    );
+    this.name = "OpenGeniSecureContextRequiredError";
+    this.reason = reason;
+  }
+}
+
 function decodeApiErrorBody(body: string): {
   code: string | undefined;
   message: string | undefined;

package/src/index.ts

@@ -26,10 +26,18 @@ export type {
 export {
   OpenGeniApiContractMismatchError,
   OpenGeniApiError,
+  OpenGeniSecureContextRequiredError,
   OpenGeniSessionListCursorError,
   OpenGeniStreamError,
   isRetryableStreamError,
 } from "./errors";
+export type { OpenGeniSecureContextRequiredReason } from "./errors";
+export {
+  AUTOMATIC_SESSION_TITLE_FALLBACK,
+  deriveSessionDisplayTitle,
+  sessionTitleIsPending,
+} from "./session-titles";
+export type { SessionDisplayTitleInput, SessionDisplayTitleOptions } from "./session-titles";
 export {
   formatSseEvent,
   proxySessionEventStream,
@@ -188,6 +196,8 @@ export {
 } from "./company-profile";
 export type {
   ActivateCompanyProfileRevisionRequest,
+  CompanyProfileAgentPolicy,
+  CompanyProfileAgentPolicyMode,
   CompanyProfileActivationEvent,
   CompanyProfileContent,
   CompanyProfileDiffRequest,
@@ -201,6 +211,7 @@ export type {
   CompanyProfileRevisionIdentity,
   RollbackCompanyProfileRequest,
   UpdateCompanyProfileRequest,
+  UpdateCompanyProfileAgentPolicyRequest,
 } from "./company-profile";
 export type {
   ActivateWorkspaceInstructionPolicyRequest,
@@ -469,6 +480,7 @@ export type {
   EndSessionRealtimeRequest,
   ModelAvailabilityV1,
   ModelBillingAttributionV1,
+  ModelCostClassV1,
   ModelCapabilitiesV1,
   ModelCapabilityStateV1,
   ModelCapabilitySupportV1,
@@ -484,12 +496,21 @@ export type {
   SessionRealtimeState,
   WorkspaceModelCatalogModel,
   WorkspaceModelCatalogResponse,
+  WorkspaceGatewayCustomModel,
+  WorkspaceGatewayCustomModelsResponse,
+  CreateWorkspaceGatewayCustomModelRequest,
+  DeleteWorkspaceGatewayCustomModelRequest,
+  WorkspaceOpenRouterCustomModel,
+  WorkspaceOpenRouterCustomModelsResponse,
+  CreateWorkspaceOpenRouterCustomModelRequest,
+  DeleteWorkspaceOpenRouterCustomModelRequest,
   WorkspaceModelAccessPolicy,
   WorkspaceRealtimeModelCatalogItem,
   WorkspaceRealtimeModelCatalogResponse,
   CodexAccount,
   CodexAccountOverview,
   CodexAccountsResponse,
+  OrganizationCodexAccountsResponse,
   CodexAllocatorUpdate,
   CodexAccountSwitchedPayload,
   CodexConnectionStatus,
@@ -514,6 +535,8 @@ export type {
   CodexRotationSettings,
   CodexUsage,
   CodexUsageMap,
+  WorkspaceCodexSubscriptionMode,
+  WorkspaceCodexSubscriptionSource,
   CodexUsagePayload,
   CodexUsageWindow,
   CompactSessionContextResult,
@@ -521,6 +544,7 @@ export type {
   CompleteFileUploadResponse,
   ConnectionKind,
   ConnectionMetadata,
+  McpConnectionAuthoritySelection,
   ConnectionOwnership,
   ConnectionResponse,
   ConnectionStatus,
@@ -549,6 +573,7 @@ export type {
   AddDocumentRequest,
   CreateApiKeyRequest,
   CreateApiKeyResponse,
+  CreateOrganizationApiKeyRequest,
   CreateCapabilityCatalogItemRequest,
   OpenGeniSlackBotInstallRequest,
   OpenGeniSlackBotInstallStart,
@@ -577,6 +602,8 @@ export type {
   CreateVariableSetRequest,
   CreateWorkspaceEnvironmentRequest,
   CreateWorkspaceRequest,
+  EnsureWorkspaceRequest,
+  EnsureWorkspaceResponse,
   DiscoverMcpCapabilitiesResponse,
   InstallSkillRequest,
   InstallLibrarySkillRequest,
@@ -677,6 +704,7 @@ export type {
   ListConnectionsResponse,
   ListPacksResponse,
   ListSlackUserLinkAccessRequestsResponse,
+  ListWorkspaceMemberCandidatesResponse,
   ListWorkspaceMembersResponse,
   McpServerConnectionRef,
   McpPersonalConnectionDelegation,
@@ -995,6 +1023,7 @@ export type {
   WorkspaceEnvironment,
   WorkspaceEnvironmentVariableMetadata,
   WorkspaceMember,
+  WorkspaceMemberCandidate,
   PreviewSkillImportRequest,
   ApiIntegrationAuthPreview,
   ApiIntegrationInstallationSummary,

package/src/interaction.ts

@@ -1558,6 +1558,12 @@ export interface InteractionTransport {
     targetId: string,
     options?: OpenGeniRequestOptions,
   ): Promise<ComputerObservation>;
+  captureComputerTarget(
+    workspaceId: string,
+    computerSessionId: string,
+    targetId: string,
+    options?: OpenGeniRequestOptions,
+  ): Promise<ComputerFrame>;
   actInComputer(
     workspaceId: string,
     computerSessionId: string,
@@ -2402,6 +2408,10 @@ export class ComputerSessionResource {
     return await this.transport.observeComputerTarget(this.workspaceId, this.id, targetId, options);
   }
 
+  async capture(targetId: string, options: OpenGeniRequestOptions = {}): Promise<ComputerFrame> {
+    return await this.transport.captureComputerTarget(this.workspaceId, this.id, targetId, options);
+  }
+
   async act(
     request: ComputerActionRequest,
     options: OpenGeniRequestOptions = {},
@@ -2791,6 +2801,28 @@ export function parseComputerFrameMetadata(value: unknown): ComputerFrameMetadat
   return metadata;
 }
 
+export function decodeComputerFrameMetadataHeader(value: string): ComputerFrameMetadata {
+  if (!value || value.length > 32 * 1024 || !/^[A-Za-z0-9_-]+$/u.test(value)) {
+    throw new Error("computer frame metadata header is invalid");
+  }
+  const normalized = value.replace(/-/gu, "+").replace(/_/gu, "/");
+  const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "=");
+  let decoded: string;
+  try {
+    decoded = atob(padded);
+  } catch {
+    throw new Error("computer frame metadata header is invalid");
+  }
+  const bytes = Uint8Array.from(decoded, (character) => character.charCodeAt(0));
+  let metadata: unknown;
+  try {
+    metadata = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+  } catch {
+    throw new Error("computer frame metadata header is invalid");
+  }
+  return parseComputerFrameMetadata(metadata);
+}
+
 function newestRelevantBrowser(
   sessions: readonly BrowserSession[],
   associationSessionId: string,

package/src/model-picker-order.ts

@@ -0,0 +1,6 @@
+export {
+  compareModelPickerOrder,
+  modelPickerBillingClassFor,
+  type ModelPickerBillingCandidate,
+  type ModelPickerBillingClass,
+} from "@opengeni/contracts/model-picker-order";

package/src/realtime.ts

@@ -30,6 +30,7 @@ import type { SessionRealtimeModel, WorkspaceRealtimeModelCatalogResponse } from
 export type SessionRealtimeClientLike = CodexRealtimeControllerClient & {
   getWorkspaceRealtimeModelCatalog(
     workspaceId: string,
+    options?: { signal?: AbortSignal | undefined },
   ): Promise<WorkspaceRealtimeModelCatalogResponse>;
 };
 

package/src/session-titles.ts

@@ -0,0 +1,84 @@
+import {
+  AUTOMATIC_SESSION_TITLE_FALLBACK,
+  boundAutomaticSessionTitle,
+  containsSensitiveAutomaticSessionTitleValue,
+} from "@opengeni/contracts/session-titles";
+import type { Session } from "./types";
+
+export { AUTOMATIC_SESSION_TITLE_FALLBACK };
+
+// Session creation accepts a body far larger than a navigation label. Bound
+// the source before any replace/split/normalization so a persisted large prompt
+// cannot amplify memory or CPU on every browser render.
+const PROMPT_PREVIEW_SCAN_MAX_CODE_UNITS = 4_096;
+
+function deriveOpeningPromptPreview(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+
+  const firstLine = value
+    .slice(0, PROMPT_PREVIEW_SCAN_MAX_CODE_UNITS)
+    .replace(/[\u0000-\u001f\u007f-\u009f]+/gu, "\n")
+    .split(/\n+/u)
+    .map((line) => line.trim())
+    .find(Boolean);
+  if (!firstLine) return null;
+  if (containsSensitiveAutomaticSessionTitleValue(firstLine)) return null;
+
+  const preview = boundAutomaticSessionTitle(firstLine.replace(/\s+/gu, " "))
+    .replace(/[\s.!?,;:\-–—]+$/u, "")
+    .trim();
+  if (!preview) return null;
+  return preview;
+}
+
+export type SessionDisplayTitleInput = {
+  title?: Session["title"] | undefined;
+  titleSource?: Session["titleSource"] | undefined;
+  initialMessage?: Session["initialMessage"] | null | undefined;
+  metadata?: Readonly<Record<string, unknown>> | undefined;
+};
+
+export type SessionDisplayTitleOptions = {
+  /** Optional metadata fields to try before the opening-prompt preview. */
+  metadataKeys?: readonly string[] | undefined;
+};
+
+/**
+ * Whether the durable title still represents the automatic-title pending state.
+ * A user-authored title always wins, even when its literal value is the fallback.
+ */
+export function sessionTitleIsPending(input: SessionDisplayTitleInput): boolean {
+  const title = input.title?.trim() ?? "";
+  return input.titleSource !== "user" && (!title || title === AUTOMATIC_SESSION_TITLE_FALLBACK);
+}
+
+/**
+ * Derive the title a client should display for a session.
+ *
+ * A semantic agent title or human rename wins. While automatic naming is still
+ * pending, clients show a short, sensitive-safe preview of the opening prompt;
+ * the preview is never persisted as title metadata and is replaced naturally
+ * when `session.title_set` arrives. Obvious credential-, URL-, or identifier-
+ * shaped prompt prefixes retain the generic fallback.
+ */
+export function deriveSessionDisplayTitle(
+  input: SessionDisplayTitleInput,
+  options: SessionDisplayTitleOptions = {},
+): string {
+  const title = input.title?.trim() ?? "";
+  if (input.titleSource === "user") {
+    return title || AUTOMATIC_SESSION_TITLE_FALLBACK;
+  }
+  if (title && !sessionTitleIsPending(input)) {
+    return title;
+  }
+
+  for (const key of options.metadataKeys ?? []) {
+    const value = input.metadata?.[key];
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value.trim();
+    }
+  }
+
+  return deriveOpeningPromptPreview(input.initialMessage) ?? AUTOMATIC_SESSION_TITLE_FALLBACK;
+}

package/src/types.ts

@@ -329,6 +329,7 @@ export type SessionCapabilities = {
     codecs: ("h264-mp4" | "vp9-webm")[];
     reason: CapabilityUnavailableReason | null;
   };
+  /** @deprecated Use the managed ComputerSession interaction tools. */
   ComputerUse: {
     available: boolean;
     readOnly: boolean;
@@ -345,6 +346,7 @@ export type TerminalCapability = SessionCapabilities["Terminal"];
 export type GitCapability = SessionCapabilities["Git"];
 export type DesktopStreamCapability = SessionCapabilities["DesktopStream"];
 export type RecordingCapability = SessionCapabilities["Recording"];
+/** @deprecated Use the managed ComputerSession interaction tools. */
 export type ComputerUseCapability = SessionCapabilities["ComputerUse"];
 
 // ── Stream-surfacing client surface (Phase 5) ───────────────────────────────
@@ -637,6 +639,7 @@ export type McpPersonalConnectionSummary = Pick<
 
 export type ConnectionMetadata = {
   id: string;
+  authorityId?: string | undefined;
   accountId: string;
   workspaceId: string;
   subjectId: string | null;
@@ -668,6 +671,7 @@ export type CreateConnectionRequest = {
   grantedScopes?: string[] | undefined;
   expiresAt?: string | null | undefined;
   metadata?: Record<string, unknown> | undefined;
+  operationId?: string | undefined;
 };
 
 export type PersonalGitHubConnectionMetadata = {
@@ -1069,6 +1073,8 @@ export type UpdateConnectionRequest = {
   grantedScopes?: string[] | undefined;
   expiresAt?: string | null | undefined;
   metadata?: Record<string, unknown> | undefined;
+  expectedVersion?: number | undefined;
+  operationId?: string | undefined;
 };
 
 export type ConnectionResponse = {
@@ -1354,6 +1360,7 @@ export type Session = {
         pausedDescendants: number;
         failedDescendants: number;
         unreadDescendants?: number | undefined;
+        unreadFailedDescendants?: number | undefined;
         activelyWorkingDescendants?: number | undefined;
         /**
          * Earliest moment one of the counted `attentionDescendants` entered
@@ -2623,6 +2630,7 @@ export type ScheduledTaskAgentConfig = {
   model?: string | undefined;
   reasoningEffort?: ReasoningEffort | undefined;
   sandboxBackend?: SandboxBackend | undefined;
+  machineTarget?: { targetSandboxId: string; workingDir?: string | undefined } | undefined;
   goal?: GoalSpec | undefined;
   executionClass?: "incident_telemetry" | undefined;
   incidentTelemetryPreflight?: IncidentTelemetryPreflight | undefined;
@@ -2795,6 +2803,7 @@ export const KNOWN_PERMISSIONS = [
   "api_keys:manage",
   "connections:read",
   "connections:write",
+  "capabilities:manage",
   "environments:manage",
   "environments:use",
   "variable-sets:list",
@@ -3024,6 +3033,8 @@ export type ModelBillingAttributionV1 = {
   metering: "opengeni_credits" | "external";
 };
 
+export type ModelCostClassV1 = "free" | "credits" | "subscription" | "workspace";
+
 export type ModelPricingV1 = {
   inputMicrosPerMillionTokens: number;
   cachedInputMicrosPerMillionTokens?: number | undefined;
@@ -3056,7 +3067,7 @@ export type ClientModel = {
   provider: string;
   providerLabel: string;
   api: "responses" | "chat";
-  source?: "opengeni" | "codex" | "supergrok" | "workspace_gateway" | undefined;
+  source?: "opengeni" | "codex" | "supergrok" | "workspace_gateway" | "openrouter" | undefined;
   contextWindowTokens?: number | undefined;
   schemaVersion?: 1 | undefined;
   aliases?: string[] | undefined;
@@ -3076,6 +3087,7 @@ export type ClientModel = {
     | undefined;
   credentialSource?: ModelCredentialSourceV1 | undefined;
   billing?: ModelBillingAttributionV1 | undefined;
+  cost?: ModelCostClassV1 | undefined;
   capabilities?: ModelCapabilitiesV1 | undefined;
   pricing?: ModelPricingScheduleV1 | undefined;
   definitionVersion?: string | undefined;
@@ -3120,6 +3132,40 @@ export type WorkspaceModelCatalogResponse = {
   models: WorkspaceModelCatalogModel[];
 };
 
+export type WorkspaceGatewayCustomModel = {
+  id: string;
+  upstreamModelId: string;
+  label: string | null;
+  version: number;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type WorkspaceGatewayCustomModelsResponse = {
+  models: WorkspaceGatewayCustomModel[];
+};
+
+export type CreateWorkspaceGatewayCustomModelRequest = {
+  operationId: string;
+  upstreamModelId: string;
+  label?: string | undefined;
+};
+
+export type DeleteWorkspaceGatewayCustomModelRequest = {
+  expectedVersion: number;
+  operationId: string;
+};
+
+export type WorkspaceOpenRouterCustomModel = WorkspaceGatewayCustomModel;
+
+export type WorkspaceOpenRouterCustomModelsResponse = {
+  models: WorkspaceOpenRouterCustomModel[];
+};
+
+export type CreateWorkspaceOpenRouterCustomModelRequest = CreateWorkspaceGatewayCustomModelRequest;
+
+export type DeleteWorkspaceOpenRouterCustomModelRequest = DeleteWorkspaceGatewayCustomModelRequest;
+
 /**
  * The workspace's hard model/provider allowlist. `null` means unrestricted for
  * that dimension; an empty array is an explicit total block.
@@ -3156,6 +3202,23 @@ export type CodexConnectionStatus = {
   } | null;
   /** How many Codex accounts the workspace has connected. */
   accountCount?: number;
+  source?: WorkspaceCodexSubscriptionSource;
+};
+
+export type WorkspaceCodexSubscriptionMode =
+  | "automatic"
+  | "workspace"
+  | "organization"
+  | "disabled";
+
+export type WorkspaceCodexSubscriptionSource = {
+  accountId: string;
+  workspaceId: string;
+  workspaceKind: "personal" | "shared";
+  mode: WorkspaceCodexSubscriptionMode;
+  effectiveSource: "workspace" | "organization" | "disabled";
+  workspaceAvailable: boolean;
+  organizationAvailable: boolean;
 };
 
 /**
@@ -3205,6 +3268,7 @@ export type CodexUsagePayload = {
 /** One connected Codex (ChatGPT) account in a workspace (multi-account P1). Metadata only. */
 export type CodexAccount = {
   id: string;
+  source?: "workspace" | "organization";
   chatgptAccountId?: string | null;
   label?: string | null;
   email?: string | null;
@@ -3317,6 +3381,7 @@ export type CodexRotationSettings = {
 export type CodexAccountsResponse = {
   accounts: CodexAccount[];
   activeAccountId: string | null;
+  source?: WorkspaceCodexSubscriptionSource;
   /** Added by Apps-aware servers; absent on older same-major deployments. */
   apps?: {
     available: boolean;
@@ -3328,6 +3393,8 @@ export type CodexAccountsResponse = {
   settings: CodexRotationSettings;
 };
 
+export type OrganizationCodexAccountsResponse = Omit<CodexAccountsResponse, "apps" | "source">;
+
 export type CodexAppsUpdate = {
   credentialId: string | null;
   version: number;
@@ -3467,6 +3534,8 @@ export type ClientAuthConfig =
       session: "cookie";
       /** Defaults to true when omitted by an older deployment. */
       emailVerificationRequired?: boolean;
+      /** Configured managed sign-in providers; omitted by older deployments. */
+      socialProviders?: ("google" | "github")[];
     };
 
 // Kept value-identical to @opengeni/contracts and pinned by the SDK contract
@@ -3492,6 +3561,7 @@ export type ClientConfig = {
   models: ClientModel[];
   defaultReasoningEffort: ReasoningEffort;
   allowedReasoningEfforts: ReasoningEffort[];
+  defaultSandboxBackend?: SandboxBackend | undefined;
   mcpServers: { id: string; name: string }[];
   /** Deployment defaults and hard maximum for built-in OpenGeni session tools. */
   firstPartyMcpTools?:
@@ -4217,6 +4287,20 @@ export type CreateWorkspaceRequest = {
   agentInstructions?: string | null | undefined;
 };
 
+export type EnsureWorkspaceRequest = {
+  accountId: string;
+  externalSource: string;
+  externalId: string;
+  name: string;
+  slug?: string | undefined;
+  agentInstructions?: string | null | undefined;
+};
+
+export type EnsureWorkspaceResponse = {
+  workspace: Workspace;
+  created: boolean;
+};
+
 export type UpdateWorkspaceRequest = {
   name?: string | undefined;
   slug?: string | null | undefined;
@@ -4251,6 +4335,12 @@ export type CreateApiKeyResponse = {
   token: string;
 };
 
+export type CreateOrganizationApiKeyRequest = {
+  name: string;
+  description?: string | undefined;
+  expiresAt?: string | undefined;
+};
+
 export type ListApiKeysResponse = {
   apiKeys: ApiKey[];
 };
@@ -4270,8 +4360,20 @@ export type ListWorkspaceMembersResponse = {
   members: WorkspaceMember[];
 };
 
+export type WorkspaceMemberCandidate = {
+  organizationMembershipId: string;
+  subjectId: string;
+  name: string | null;
+  email: string | null;
+  organizationRole: "owner" | "admin" | "member";
+};
+
+export type ListWorkspaceMemberCandidatesResponse = {
+  members: WorkspaceMemberCandidate[];
+};
+
 export type AddWorkspaceMemberRequest = {
-  email: string;
+  organizationMembershipId: string;
   role?: string | undefined;
   permissions: Permission[];
 };
@@ -4781,6 +4883,7 @@ export type ScheduledTaskAgentConfigInput = {
   model?: string | undefined;
   reasoningEffort?: ReasoningEffort | undefined;
   sandboxBackend?: SandboxBackend | undefined;
+  machineTarget?: { targetSandboxId: string; workingDir?: string | undefined } | undefined;
   goal?: GoalSpec | undefined;
   executionClass?: "incident_telemetry" | undefined;
   incidentTelemetryPreflight?: IncidentTelemetryPreflightInput | undefined;