@opengeni/sdk 0.46.0 → 0.52.1

package/src/types.ts

@@ -1,9 +1,9 @@
 import type { WorkspaceTranscriptionPolicy } from "./transcription";
 
 // Hand-written mirrors of the public wire shapes in `@opengeni/contracts`.
-// The SDK keeps zero runtime dependencies so it stays framework-agnostic and
-// publishable on its own; `test/contract-parity.test.ts` pins these types to
-// the contracts package so drift fails the gate instead of shipping.
+// Ordinary SDK entries stay framework-agnostic and do not import the contracts
+// runtime; `test/contract-parity.test.ts` pins these types to the contracts
+// package so drift fails the gate instead of shipping.
 
 export type CodexRealtimeWebrtcVersion = "v3";
 export type CodexRealtimeVoice =
@@ -287,6 +287,7 @@ export type SessionCapabilities = {
     shell: string;
     url: string | null;
     token: string | null;
+    expiresAt: string | null;
     reason: CapabilityUnavailableReason | null;
   };
   Git: {
@@ -343,8 +344,8 @@ export type ComputerUseCapability = SessionCapabilities["ComputerUse"];
 // the capability-gated client (`@opengeni/react`) drives. The desktop pixel
 // plane rides Channel B (direct-to-provider noVNC); the structured terminal/
 // files/git surfaces ride Channel A (the existing event spine + the synchronous
-// fs/git/terminal point queries above). These are TYPES only (the SDK keeps zero
-// runtime deps); the contract-parity test pins them.
+// fs/git/terminal point queries above). These are TYPES only, so ordinary SDK
+// entries do not reach the contracts runtime; the contract-parity test pins them.
 
 // Mirror of `@opengeni/contracts` StreamUrlRotatedPayload — the Channel-A event
 // the client folds in to hot-swap its noVNC socket on a box rollover, fenced on
@@ -374,12 +375,14 @@ export type StreamRevokedPayload = {
 
 // Mirror of `@opengeni/contracts` AttachViewerRequest. Omitting `viewerId` mints
 // a fresh holder id (returned on the response, carried through heartbeat/detach).
-// `desktop:true` opts into the un-redacted pixel plane (the consent-gated noVNC
-// stream); a terminal/files-only warm attach omits it (defaults false) so it
-// warms the box + mints the pty-ws terminal cell WITHOUT tripping the consent 409.
+// Plane flags are exact: credentials are minted only for the requested live
+// surfaces and each surface enforces its own permission. An omitted plane set is
+// retained as the legacy terminal-only request; current clients send all flags.
 export type AttachViewerRequest = {
   viewerId?: string | undefined;
   desktop?: boolean | undefined;
+  terminal?: boolean | undefined;
+  files?: boolean | undefined;
 };
 
 // Mirror of `@opengeni/contracts` ViewerHolder + the P4.2 desktop-stream fields
@@ -402,8 +405,8 @@ export type AttachViewerResponse = ViewerHolder & {
   streamToken: string | null;
   streamExpiresAt: string | null;
   resolution: [number, number] | null;
-  transport: "vnc-ws" | null;
-  client: "novnc" | null;
+  transport: "vnc-ws" | "relay-frames" | null;
+  client: "novnc" | "frames" | null;
   // The scoped ttyd PTY-over-websocket address minted for THIS holder — the REAL
   // interactive terminal, symmetric with the desktop pixel plane (same Modal
   // tunnel, same scoped stream token). Populated on a warm box; null when the
@@ -412,6 +415,7 @@ export type AttachViewerResponse = ViewerHolder & {
   // `terminalTransport` is "pty-ws" iff a live `terminalUrl` was minted.
   terminalUrl: string | null;
   terminalToken: string | null;
+  terminalExpiresAt: string | null;
   terminalTransport: "pty-ws" | null;
 };
 
@@ -461,7 +465,7 @@ export type RepositoryResourceRef = {
   githubRepositoryId?: number | undefined;
 };
 
-/** Value mirror of `@opengeni/contracts`; parity-tested without adding an SDK runtime dependency. */
+/** Value mirror of `@opengeni/contracts`; parity-tested without importing it from ordinary SDK entries. */
 export const DEFAULT_FILE_RESOURCE_MOUNT_ROOT = ".opengeni/files" as const;
 
 export type FileResourceRef = {
@@ -641,6 +645,33 @@ export type OpenGeniSlackBotInstallStart = {
   expiresAt: string;
 };
 
+export type SlackInstallationBindingState = "active" | "quarantined";
+
+export type SlackInstallationBinding = {
+  id: string;
+  accountId: string;
+  accountName: string;
+  workspaceId: string;
+  workspaceName: string;
+  connectionId: string;
+  connectionStatus: ConnectionStatus;
+  connectionVersion: number;
+  slackTeamId: string;
+  slackTeamName: string;
+  botId: string;
+  botUserId: string;
+  botDisplayName: "OpenGeni";
+  state: SlackInstallationBindingState;
+  quarantineReason: string | null;
+  version: number;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type ListSlackInstallationBindingsResponse = {
+  bindings: SlackInstallationBinding[];
+};
+
 export type GoogleDriveTargetScope = "user" | "workspace" | "organization";
 export type ConnectorDocumentDestinationAuthority = "organization" | "workspace" | "personal";
 export type ConnectorDocumentDestinationSelection = {
@@ -680,13 +711,15 @@ export type GoogleDriveSelectedSource = {
   /** @deprecated Missing destinations resolve to the current workspace boundary. */
   targetScope?: GoogleDriveTargetScope | undefined;
   syncCadence: GoogleDriveSyncCadence;
+  syncEnabled: boolean;
+  configGeneration: number;
   readPolicy: GoogleDriveReadPolicy;
   selectedAt: string;
 };
 
 export type GoogleDriveConnectionMetadata = {
   credentialRole: "google_drive_metadata";
-  credentialLabel: "Google Drive metadata browser";
+  credentialLabel: "Google Drive read-only source sync" | "Google Drive metadata browser";
   googlePermissionId: string;
   googleEmail: string;
   googleDisplayName: string | null;
@@ -739,15 +772,118 @@ export type GoogleDriveBrowseResponse = {
   incompleteSearch: boolean;
 };
 
+export type AtlassianSourceKind = "jira_project" | "confluence_space";
+export type AtlassianSyncCadence = "manual" | "hourly" | "daily";
+export type AtlassianReadPolicy = "allow" | "ask" | "block";
+export type AtlassianConnectionLifecycle = {
+  state:
+    | "active"
+    | "paused"
+    | "token_revoked"
+    | "app_removed"
+    | "disconnected"
+    | "reconnect_required"
+    | "reconsent_required";
+  recoverable: boolean;
+  observedAt: string;
+};
+export type AtlassianSelectedSource = {
+  id: string;
+  cloudId: string;
+  siteName: string;
+  siteUrl: string;
+  resourceId: string;
+  key: string;
+  name: string;
+  kind: AtlassianSourceKind;
+  destination?: ConnectorDocumentDestination | undefined;
+  syncCadence: AtlassianSyncCadence;
+  syncEnabled: boolean;
+  configGeneration: number;
+  readPolicy: AtlassianReadPolicy;
+  selectedAt: string;
+};
+export type AtlassianConnectionMetadata = {
+  credentialRole: "atlassian_knowledge";
+  credentialLabel: "Atlassian read-only knowledge sync";
+  atlassianAccountId: string;
+  displayName: string;
+  email?: string | null | undefined;
+  sites: Array<{
+    cloudId: string;
+    name: string;
+    url: string;
+    products: Array<"jira" | "confluence">;
+  }>;
+  verifiedAt: string;
+  accessMode: "readonly";
+  lifecycle?: AtlassianConnectionLifecycle | undefined;
+  documentDestination?: ConnectorDocumentDestination | undefined;
+  selectedSources: AtlassianSelectedSource[];
+  [key: string]: unknown;
+};
+export type AtlassianOAuthStartResponse = { authorizationUrl: string; expiresAt: string };
+export type AtlassianLifecycleActionRequest = {
+  action: "pause" | "resume";
+  expectedVersion: number;
+};
+export type AtlassianDisconnectRequest = { expectedVersion: number; idempotencyKey: string };
+export type AtlassianBrowseItem = {
+  id: string;
+  cloudId: string;
+  siteName: string;
+  siteUrl: string;
+  resourceId: string;
+  key: string;
+  name: string;
+  kind: AtlassianSourceKind;
+  description: string | null;
+  webUrl: string;
+};
+export type AtlassianBrowseResponse = {
+  connection: ConnectionMetadata;
+  items: AtlassianBrowseItem[];
+};
+
 export type SaveGoogleDriveSourceRequest = {
   sources: Array<Pick<GoogleDriveBrowseItem, "id" | "name" | "mimeType" | "driveId">>;
   destination?: ConnectorDocumentDestinationSelection | undefined;
   /** @deprecated Legacy requests resolve to workspace authority. */
   targetScope?: GoogleDriveTargetScope | undefined;
   syncCadence: GoogleDriveSyncCadence;
+  syncEnabled: boolean;
+  readPolicy: GoogleDriveReadPolicy;
+};
+
+export type GoogleDriveKnowledgeSourceItem = {
+  id: string;
+  name: string;
+  mimeType: string;
+  driveId?: string | undefined;
+  sourceKind: "my_drive" | "shared_drive" | "folder";
+  includeDescendants: boolean;
+};
+
+export type GoogleDriveKnowledgeSourceDestination = {
+  authorityKind: ConnectorDocumentDestinationAuthority;
+  authorityAccountId: string;
+  authorityWorkspaceId?: string | undefined;
+  authoritySubjectId?: string | undefined;
+  collectionId?: string | undefined;
+};
+
+export type GoogleDriveKnowledgeSourceConfig = {
+  sources: GoogleDriveKnowledgeSourceItem[];
+  destination: GoogleDriveKnowledgeSourceDestination;
+  syncCadence: GoogleDriveSyncCadence;
   readPolicy: GoogleDriveReadPolicy;
 };
 
+export type SaveGoogleDriveIntegrationSourceRequest = SaveGoogleDriveSourceRequest & {
+  expectedVersion?: number | undefined;
+  idempotencyKey: string;
+};
+
 export type UpdateConnectionRequest = {
   providerDomain?: string | undefined;
   subjectId?: string | null | undefined;
@@ -960,6 +1096,47 @@ export type SessionListResponse = {
   nextCursor: string | null;
 };
 
+/** Compact, bounded session projection for workspace agent-topology browsers. */
+export type AgentTopologySession = {
+  id: string;
+  title: string | null;
+  titleTruncated: boolean;
+  parentSessionId: string | null;
+  rootSessionId: string;
+  nestedAgentDepth: number;
+  ancestorPath: Array<{ id: string; title: string | null; titleTruncated: boolean }>;
+  status: SessionStatus;
+  pause: {
+    state: "active" | "paused";
+    additionalBlockerCount: number;
+    source: {
+      kind: "session" | "workspace";
+      sessionId?: string | undefined;
+      displayName: string;
+      displayNameTruncated: boolean;
+    } | null;
+  };
+  children: {
+    directChildren: number;
+    totalDescendants: number;
+    runningDescendants: number;
+    queuedDescendants: number;
+    attentionDescendants: number;
+    pausedDescendants: number;
+    failedDescendants: number;
+    truncated: boolean;
+  };
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type AgentTopologyPageResponse = {
+  sessions: AgentTopologySession[];
+  total: number;
+  hasMore: boolean;
+  nextCursor: string | null;
+};
+
 export type UpdateSessionPinRequest = {
   pinned: boolean;
   expectedVersion?: number;
@@ -996,6 +1173,39 @@ export type SessionTurnSource =
   | "system"
   | "compaction";
 
+export type TimelineAnnotationSourceKind = "user_message" | "assistant_message" | "tool_output";
+
+export type TimelineAnnotationSourceEventType =
+  | "user.message"
+  | "agent.message.completed"
+  | "agent.toolCall.output";
+
+export type TimelineAnnotationSource = {
+  kind: TimelineAnnotationSourceKind;
+  eventId: string;
+  eventType: TimelineAnnotationSourceEventType;
+  sequence: number;
+  turnId: string | null;
+  startOffset: number;
+  endOffset: number;
+  contextBefore: string;
+  contextAfter: string;
+  label?: string | undefined;
+};
+
+export type DraftTimelineAnnotation = {
+  id: string;
+  source: TimelineAnnotationSource;
+  quote: string;
+  note: string;
+};
+
+export type SubmittedTimelineAnnotation = DraftTimelineAnnotation;
+
+export type TimelineAnnotation = DraftTimelineAnnotation & {
+  ordinal: number;
+};
+
 export type SessionTurn = {
   id: string;
   workspaceId: string;
@@ -1006,6 +1216,7 @@ export type SessionTurn = {
   source: SessionTurnSource;
   position: number;
   prompt: string;
+  annotations?: TimelineAnnotation[] | undefined;
   resources: ResourceRef[];
   tools: ToolRef[];
   toolsProvided?: boolean | undefined;
@@ -1373,6 +1584,17 @@ export type ToolAuthNeededPayload = {
   selectedResources?: Array<{ id: string; kind: "repository" }> | undefined;
   authorizationUrl?: string | undefined;
   subjectId?: string | null | undefined;
+  capability?:
+    | {
+        id: string;
+        name: string;
+        kind: CapabilityKind;
+        source: CapabilitySource;
+        action: "connect" | "add_credentials" | "enable";
+        rationale: string;
+        requiredVariables: string[];
+      }
+    | undefined;
 };
 
 // Payload shapes for the high-traffic event types. `SessionEvent.payload` is
@@ -1471,9 +1693,10 @@ export type CodexFleetDecisionEventPayload = {
   } & Record<string, unknown>;
 };
 
-// Recording payloads (P4.3 — plain TS mirror of the contracts Zod schemas; the
-// SDK is zero-runtime-dep so these are TYPES, not Zod, F15). The contract-parity
-// test asserts the event-type literals; these shapes document the wire payloads.
+// Recording payloads (P4.3 — plain TS mirror of the contracts Zod schemas).
+// These are TYPES, not Zod (F15), so ordinary SDK entries remain runtime-clean.
+// The contract-parity test asserts the event-type literals; these shapes
+// document the wire payloads.
 export type RecordingMode = "manual" | "on-turn" | "on-verify";
 export type RecordingCodec = "h264-mp4" | "vp9-webm";
 export type RecordingContentType = "video/mp4" | "video/webm";
@@ -1587,6 +1810,8 @@ export type FsListResponse = {
   revision: number;
   truncated: boolean;
 };
+export type FsListBatchRequest = { requests: FsListRequest[] };
+export type FsListBatchResponse = { results: FsListResponse[] };
 export type FsReadRequest = {
   path: string;
   encoding?: FsEncoding;
@@ -1651,6 +1876,9 @@ export type GitStatusRequest = { path?: string };
 export type GitStatusResponse = {
   isRepo: boolean;
   head: string | null;
+  /** Exact commit object identity. null for unborn/non-repositories; absent on
+   *  legacy adapters. */
+  headOid?: string | null | undefined;
   detached: boolean;
   upstream: string | null;
   ahead: number;
@@ -1695,6 +1923,16 @@ export type GitDiffRequest = {
   maxBytesPerFile?: number;
 };
 export type GitDiffResponse = { files: GitFileDiff[]; revision: number };
+export type GitReadBatchItemRequest = {
+  status: GitStatusRequest;
+  diff?: GitDiffRequest;
+};
+export type GitReadBatchRequest = { requests: GitReadBatchItemRequest[] };
+export type GitReadBatchItemResponse = {
+  status: GitStatusResponse;
+  diff?: GitDiffResponse;
+};
+export type GitReadBatchResponse = { results: GitReadBatchItemResponse[] };
 export type GitLogRequest = {
   path?: string;
   ref?: string;
@@ -1749,12 +1987,18 @@ export type WorkspaceCaptureFile = {
 export type WorkspaceCaptureRepo = {
   root: string;
   head: string | null;
+  /** Exact HEAD commit object identity. null for unborn repositories; absent
+   *  on legacy captures. */
+  headOid?: string | null | undefined;
   detached: boolean;
   upstream: string | null;
   ahead: number;
   behind: number;
   status: GitFileStatus[];
   diff: GitFileDiff[];
+  /** Current branch vs the remote default branch. Absent on legacy captures or
+   *  repositories whose remote default ref could not be resolved. */
+  branchDiff?: GitFileDiff[] | undefined;
 };
 export type WorkspaceCaptureDegradedReason =
   | "repository_discovery_command_failed"
@@ -1875,7 +2119,7 @@ export type SessionStructuredCapabilities = {
 
 export type ScheduledTaskStatus = "active" | "paused";
 
-export type ScheduledTaskRunMode = "new_session_per_run" | "reusable_session";
+export type ScheduledTaskRunMode = "new_session_per_run" | "reusable_session" | "existing_session";
 
 export type ScheduledTaskOverlapPolicy = "allow_concurrent" | "skip" | "buffer_one";
 
@@ -1889,6 +2133,7 @@ export type ScheduledTaskDayOfWeek =
   | "SATURDAY";
 
 export type ScheduledTaskScheduleSpec =
+  | { type: "manual" }
   | { type: "once"; runAt: string; timeZone: string }
   | {
       type: "interval";
@@ -1917,6 +2162,44 @@ export type ScheduledTaskAgentConfig = {
   maxNestedAgentDepth?: number | undefined;
 };
 
+export type ScopedKnowledgeScope =
+  | { kind: "organization"; workspaceId: null; subjectId: null }
+  | { kind: "workspace"; workspaceId: string; subjectId: null }
+  | { kind: "personal"; workspaceId: string | null; subjectId: string };
+
+export type KnowledgeSourceSyncLimits = {
+  maxItems: number;
+  maxBytes: number;
+  maxFileBytes: number;
+  maxProviderRequests: number;
+  maxElapsedSeconds: number;
+  maxConcurrency: number;
+  maxFailureDetails: number;
+};
+
+export type ScheduledTaskAction =
+  | { kind: "agent_turn" }
+  | {
+      kind: "knowledge_source_sync";
+      sourceId: string;
+      sourceGeneration: number;
+      sourceLifecycleGeneration: number;
+      sourceConfigGeneration: number;
+      controlWorkspaceId: string;
+      providerCoordinationKey: string;
+      connection: {
+        connectionId: string;
+        connectionVersion: number;
+        providerDomain: string;
+        kind: ConnectionKind;
+        ownerSubjectId: string;
+      };
+      destination: ScopedKnowledgeScope;
+      initiatingSubjectId: string;
+      allDescendants: boolean;
+      limits: KnowledgeSourceSyncLimits;
+    };
+
 export type ScheduledTask = {
   id: string;
   accountId: string;
@@ -1927,10 +2210,12 @@ export type ScheduledTask = {
   temporalScheduleId: string;
   runMode: ScheduledTaskRunMode;
   overlapPolicy: ScheduledTaskOverlapPolicy;
+  action: ScheduledTaskAction;
   agentConfig: ScheduledTaskAgentConfig;
   createdBy?: TurnInitiator | undefined;
   createdByContext?: TurnInitiatorContext | undefined;
   personalConnections?: McpPersonalConnectionSummary[] | undefined;
+  targetSessionId: string | null;
   reusableSessionId: string | null;
   variableSetId: string | null;
   /** @deprecated use variableSetId */
@@ -2038,10 +2323,16 @@ export const KNOWN_PERMISSIONS = [
   "connections:write",
   "environments:manage",
   "environments:use",
+  "variable-sets:list",
+  "variable-sets:read",
+  "variable-sets:write",
   "variable-sets:manage",
   "variable-sets:use",
+  "secrets:list",
+  "secrets:read",
+  "secrets:write",
   "mcp_servers:attach",
-  "toolspace:call",
+  "codemode:call",
   "goals:manage",
   "enrollments:read",
   "enrollments:manage",
@@ -2075,6 +2366,7 @@ export type FirstPartyMcpToolName =
   | "sandbox_swap"
   | "run_on"
   | "sandbox_provision"
+  | "connected_machine_remove"
   | "rig_list"
   | "rig_get"
   | "rig_propose_change"
@@ -2089,10 +2381,27 @@ export type FirstPartyMcpToolName =
   | "session_resume"
   | "session_steer"
   | "set_other_session_title"
+  | "interaction_discover"
+  | "browser_open"
+  | "browser_tabs"
+  | "browser_observe"
+  | "browser_act"
+  | "browser_debug"
+  | "browser_identity"
+  | "browser_publish"
+  | "browser_lifecycle"
+  | "computer_open"
+  | "computer_targets"
+  | "computer_observe"
+  | "computer_act"
+  | "computer_lifecycle"
   | "variable_set_list"
   | "environment_list"
+  | "variable_set_get_variable"
   | "variable_set_set_variable"
   | "environment_set_variable"
+  | "capability_catalog_search"
+  | "capability_authorization_request"
   | "github_connect_link"
   | "github_repositories_list"
   | "social_connections_list"
@@ -2103,6 +2412,18 @@ export type FirstPartyMcpToolName =
   | "social_thread_fetch"
   | "social_posts_sync"
   | "social_post_reply"
+  | "x_accounts_list"
+  | "x_search_live"
+  | "x_mentions_live"
+  | "x_thread_fetch"
+  | "x_posts_sync"
+  | "x_post_reply"
+  | "reddit_accounts_list"
+  | "reddit_search_live"
+  | "reddit_mentions_live"
+  | "reddit_thread_fetch"
+  | "reddit_posts_sync"
+  | "reddit_post_reply"
   | "scheduled_tasks_list"
   | "scheduled_tasks_get"
   | "scheduled_tasks_create"
@@ -2121,11 +2442,22 @@ export type FirstPartyMcpToolName =
   | "slack_bot_file_content"
   | "slack_bot_post_message"
   | "slack_bot_delete_message"
+  | "atlassian_sources_list"
+  | "atlassian_search"
+  | "atlassian_get"
   | "artifacts_list"
   | "artifacts_get_source"
   | "artifacts_create"
   | "artifacts_publish"
-  | "artifacts_rollback";
+  | "artifacts_rollback"
+  | "editable_artifact_list"
+  | "editable_artifact_create"
+  | "editable_artifact_import"
+  | "editable_artifact_get"
+  | "editable_artifact_inspect"
+  | "editable_artifact_apply"
+  | "editable_artifact_export"
+  | "editable_artifact_export_status";
 
 export type ProductAccessMode = "local" | "configured" | "managed";
 
@@ -2516,7 +2848,7 @@ export type ClientAuthConfig =
 
 // Kept value-identical to @opengeni/contracts and pinned by the SDK contract
 // parity suite. The SDK has no runtime dependency on the Zod contracts package.
-export const OPENGENI_API_CONTRACT_REVISION = "2026-07-workspace-artifacts-v1" as const;
+export const OPENGENI_API_CONTRACT_REVISION = "2026-08-social-provider-tools-v1" as const;
 export const OPENGENI_API_CONTRACT_HEADER = "x-opengeni-api-contract" as const;
 /** Bounded request/response identifier shared by browser, ingress, and API diagnostics. */
 export const OPENGENI_CORRELATION_HEADER = "x-opengeni-correlation-id" as const;
@@ -2736,13 +3068,15 @@ export type WorkspaceSettings = {
   maxNestedAgentDepth?: number | null | undefined;
   /** Default for new Codex sessions; absent ⇒ remote_v2. */
   codexCompactionDefault?: "remote_v2" | "portable" | undefined;
+  /** Whether agents may invoke the built-in structured human-input tool. */
+  agentHumanInputEnabled?: boolean | undefined;
   slackReactionSummon?: WorkspaceSlackReactionSummonSettings | undefined;
   [key: string]: unknown;
 };
 
 export type WorkspaceSlackReactionSummonSettings = {
   enabled: boolean;
-  emoji: string;
+  emoji: "genie";
   channelPolicy: { mode: "bot_member" } | { mode: "allowlist"; channelIds: string[] };
 };
 
@@ -2767,6 +3101,7 @@ export type UpdateWorkspaceSettingsRequest = {
   transcription?: WorkspaceTranscriptionPolicy | undefined;
   maxNestedAgentDepth?: number | null | undefined;
   codexCompactionDefault?: "remote_v2" | "portable" | undefined;
+  agentHumanInputEnabled?: boolean | undefined;
   slackReactionSummon?: WorkspaceSlackReactionSummonSettings | undefined;
   [key: string]: unknown;
 };
@@ -2846,6 +3181,48 @@ export type UpdateWorkspaceMemberRequest = {
   permissions: Permission[];
 };
 
+export type SlackUserLinkAccessRequestStatus =
+  | "prepared"
+  | "pending"
+  | "completed"
+  | "denied"
+  | "cancelled"
+  | "expired";
+
+/** Token-free durable projection of one signed Slack identity-link intent. */
+export type SlackUserLinkAccessRequest = {
+  id: string;
+  workspaceId: string;
+  workspaceDisplayName: string | null;
+  subjectLabel: string | null;
+  status: SlackUserLinkAccessRequestStatus;
+  version: number;
+  expiresAt: string;
+  requestedAt: string | null;
+  decidedAt: string | null;
+  completedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type PrepareSlackUserLinkAccessRequest = {
+  linkToken: string;
+};
+
+export type SlackUserLinkAccessMutationRequest = {
+  expectedVersion: number;
+  idempotencyKey: string;
+};
+
+export type ApproveSlackUserLinkAccessRequest = SlackUserLinkAccessMutationRequest & {
+  role?: string | undefined;
+  permissions: Permission[];
+};
+
+export type ListSlackUserLinkAccessRequestsResponse = {
+  requests: SlackUserLinkAccessRequest[];
+};
+
 // --- Goals -------------------------------------------------------------------
 
 export type SessionGoalStatus = "active" | "paused" | "completed";
@@ -2977,6 +3354,7 @@ export type SessionCommandReceipt = {
 export type ComposerDraft = {
   revision: number;
   text: string;
+  annotations?: DraftTimelineAnnotation[] | undefined;
   resources: ResourceRef[];
   model: string;
   reasoningEffort: ReasoningEffort;
@@ -3040,7 +3418,8 @@ export type SessionSystemUpdateKind =
   | "goal_continuation"
   | "agent_message"
   | "agent_steer_instruction"
-  | "child_terminal_result";
+  | "child_terminal_result"
+  | "media_generation_result";
 
 export type SessionSystemUpdateState =
   | "pending"
@@ -3175,10 +3554,12 @@ export type ScheduledTaskAgentConfigInput = {
   maxNestedAgentDepth?: number | undefined;
 };
 
-export type CreateScheduledTaskRequest = {
+export type CreateAgentScheduledTaskRequest = {
   name: string;
   schedule: ScheduledTaskScheduleSpec;
+  action?: { kind: "agent_turn" } | undefined;
   runMode?: ScheduledTaskRunMode | undefined;
+  targetSessionId?: string | null | undefined;
   overlapPolicy?: ScheduledTaskOverlapPolicy | undefined;
   agentConfig: ScheduledTaskAgentConfigInput;
   status?: ScheduledTaskStatus | undefined;
@@ -3190,11 +3571,26 @@ export type CreateScheduledTaskRequest = {
   metadata?: Record<string, unknown> | undefined;
 };
 
+export type CreateKnowledgeSourceSyncScheduledTaskRequest = {
+  name: string;
+  schedule: ScheduledTaskScheduleSpec;
+  action: Extract<ScheduledTaskAction, { kind: "knowledge_source_sync" }>;
+  overlapPolicy?: "skip" | "buffer_one" | undefined;
+  status?: ScheduledTaskStatus | undefined;
+  metadata?: Record<string, unknown> | undefined;
+};
+
+export type CreateScheduledTaskRequest =
+  | CreateAgentScheduledTaskRequest
+  | CreateKnowledgeSourceSyncScheduledTaskRequest;
+
 export type UpdateScheduledTaskRequest = {
   name?: string | undefined;
   schedule?: ScheduledTaskScheduleSpec | undefined;
   runMode?: ScheduledTaskRunMode | undefined;
+  targetSessionId?: string | null | undefined;
   overlapPolicy?: ScheduledTaskOverlapPolicy | undefined;
+  action?: ScheduledTaskAction | undefined;
   agentConfig?: ScheduledTaskAgentConfigInput | undefined;
   status?: ScheduledTaskStatus | undefined;
   variableSetId?: string | null | undefined;
@@ -3205,9 +3601,50 @@ export type UpdateScheduledTaskRequest = {
   metadata?: Record<string, unknown> | undefined;
 };
 
-export type ScheduledTaskRunStatus = "queued" | "dispatched" | "failed";
+export type ScheduledTaskRunStatus = "queued" | "dispatched" | "succeeded" | "skipped" | "failed";
+
+export type KnowledgeSourceSyncRunSummary = {
+  phase: "queued" | "inventory" | "transfer" | "index" | "checkpoint" | "completed" | "failed";
+  scanned: number;
+  imported: number;
+  unchanged: number;
+  skipped: number;
+  failed: number;
+  bytes: number;
+  providerRequests: number;
+  elapsedMs: number;
+  indexed: number;
+  aclPending: number;
+  retryable: boolean;
+  limitReached: "items" | "bytes" | "file_bytes" | "provider_requests" | "elapsed_time" | null;
+  checkpointed: boolean;
+  reconnectRequired: boolean;
+  failures: Array<{
+    externalObjectId: string;
+    code:
+      | "authority_changed"
+      | "connection_reconnect_required"
+      | "provider_unavailable"
+      | "provider_rejected"
+      | "provider_payload_invalid"
+      | "content_unsupported"
+      | "content_too_large"
+      | "resource_limit"
+      | "item_processing_failed"
+      | "indexing_failed"
+      | "internal_failure";
+    retryable: boolean;
+    message: string;
+  }>;
+};
 
-export type ScheduledTaskTriggerType = "scheduled" | "manual";
+export type ScheduledTaskTriggerType =
+  | "scheduled"
+  | "manual"
+  | "initial"
+  | "provider_event"
+  | "retry"
+  | "repair";
 
 export type ScheduledTaskRun = {
   id: string;
@@ -3220,6 +3657,10 @@ export type ScheduledTaskRun = {
   firedAt: string;
   sessionId: string | null;
   triggerEventId: string | null;
+  actionKind: "agent_turn" | "knowledge_source_sync";
+  knowledgeSyncRunId: string | null;
+  knowledgeSummary: KnowledgeSourceSyncRunSummary | null;
+  completedAt: string | null;
   error: string | null;
   createdAt: string;
   updatedAt: string;
@@ -3227,11 +3668,7 @@ export type ScheduledTaskRun = {
 
 // --- VariableSets -------------------------------------------------------------
 
-/**
- * Variable values are write-only by design: the API never returns a value, so
- * reads expose name + version metadata only. Values are decrypted exclusively
- * inside the worker at sandbox materialization time.
- */
+/** Generic variable-set reads expose name + version metadata only. */
 export type VariableSetVariableMetadata = {
   name: string;
   version: number;
@@ -3239,6 +3676,14 @@ export type VariableSetVariableMetadata = {
   updatedAt: string;
 };
 
+/** Dedicated permissioned plaintext response; never embedded in metadata reads. */
+export type VariableSetSecret = {
+  variableSetId: string;
+  name: string;
+  version: number;
+  value: string;
+};
+
 export type VariableSet = {
   id: string;
   accountId: string;
@@ -3290,6 +3735,40 @@ export type RigCheck = {
   command: string;
 };
 
+export type RigProviderImageBuildStatus = "building" | "ready" | "failed" | "unsupported";
+
+export type RigProviderImage = {
+  backend: SandboxBackend;
+  provider: string;
+  status: RigProviderImageBuildStatus;
+  contentHash: string;
+  setupHash: string;
+  sourceImage: string | null;
+  buildRequestId: string;
+  imageId: string | null;
+  imageDigest: string | null;
+  artifactId: string | null;
+  providerBindingKeyHash: string | null;
+  coldBootValidation?:
+    | {
+        version: 1;
+        checkedAt: string;
+      }
+    | undefined;
+  provenance: {
+    kind: "rig_verification";
+    targetKind: "change" | "version";
+    targetId: string;
+  };
+  startedAt: string;
+  finishedAt: string | null;
+  error: {
+    code: string;
+    message: string;
+    retryable: boolean;
+  } | null;
+};
+
 export type RigVersion = {
   id: string;
   rigId: string;
@@ -3300,6 +3779,7 @@ export type RigVersion = {
   credentialHooks: string[];
   defaultVariableSetIds: string[];
   changelog: string | null;
+  providerImages: Partial<Record<SandboxBackend, RigProviderImage>>;
   createdBy: string | null;
   active: boolean;
   createdAt: string;
@@ -3412,12 +3892,18 @@ export type FileAsset = {
 /** Mirrors the closed, provider-neutral retained-output contract. */
 export const RETAINED_OUTPUT_DEFAULT_PAGE_BYTES = 256 * 1024;
 export const RETAINED_OUTPUT_MAX_PAGE_BYTES = 1024 * 1024;
+export const COMPUTER_SCREENSHOT_MAX_BYTES = 32 * 1024 * 1024;
+export const GENERATED_IMAGE_MAX_BYTES = 64 * 1024 * 1024;
+export const GENERATED_VIDEO_MAX_BYTES = 512 * 1024 * 1024;
 
 export type RetainedOutputKind =
   | "tool_result"
   | "assistant_completion"
   | "internal_update"
   | "event_media"
+  | "computer_screenshot"
+  | "generated_image"
+  | "generated_video"
   | "file";
 
 export type RetainedOutputUnavailableReason =
@@ -3428,6 +3914,9 @@ export type RetainedOutputUnavailableReason =
   | "deleted"
   | "missing_storage"
   | "storage_write_failed"
+  | "quota_exceeded"
+  | "invalid_content"
+  | "oversized"
   | "unsupported";
 
 export type RetainedArtifactReference = {
@@ -3438,7 +3927,10 @@ export type RetainedArtifactReference = {
   originalBytes: number;
   sha256: string;
   retainedAt: string;
-  retention: { policy: "workspace_file"; expiresAt: null };
+  dimensions?: { width: number; height: number } | undefined;
+  retention:
+    | { policy: "workspace_file"; expiresAt: null }
+    | { policy: "session_screenshot"; expiresAt: string };
   retrieval: {
     method: "GET";
     path: string;
@@ -3455,6 +3947,157 @@ export type RetainedArtifactUnavailable = {
 
 export type RetainedArtifactMetadata = RetainedArtifactReference | RetainedArtifactUnavailable;
 
+export type GeneratedImageReceipt = {
+  type: "generated_image";
+  artifact: RetainedArtifactReference;
+  sandboxPath: string;
+};
+
+export type VideoGenerationSourceMode =
+  | "text"
+  | "first_frame"
+  | "first_and_last_frames"
+  | "image_reference"
+  | "video_reference";
+
+export type VideoGenerationResolution = "480p" | "720p";
+
+export type VideoGenerationAspectRatio =
+  | "16:9"
+  | "4:3"
+  | "1:1"
+  | "3:4"
+  | "9:16"
+  | "21:9"
+  | "adaptive";
+
+export type VideoGenerationModelCapability = {
+  modelId: string;
+  label: string;
+  providerLabel: string;
+  sourceModes: VideoGenerationSourceMode[];
+  resolutions: VideoGenerationResolution[];
+  aspectRatios: VideoGenerationAspectRatio[];
+  duration: {
+    minSeconds: number;
+    maxSeconds: number;
+    stepSeconds: number;
+  };
+  supportsAudio: boolean;
+};
+
+export type VideoGenerationCapabilities = {
+  schemaVersion: 1;
+  capabilityRevision: string;
+  defaultModelId: string;
+  models: VideoGenerationModelCapability[];
+};
+
+export type VideoGenerationPolicy = {
+  schemaVersion: 1;
+  revision: number;
+  fundingSource: VideoGenerationFundingSource;
+  enabledModelIds: string[];
+  defaultModelId: string | null;
+};
+
+export type UpdateVideoGenerationPolicyRequest = {
+  expectedRevision: number;
+  fundingSource: VideoGenerationFundingSource;
+  enabledModelIds: string[];
+  defaultModelId: string | null;
+};
+
+export type VideoGenerationFundingSource = "opengeni_credits" | "workspace_gateway";
+
+export type VideoGenerationFundingOption = {
+  source: VideoGenerationFundingSource;
+  label: string;
+  description: string;
+  available: boolean;
+  unavailableReason: string | null;
+};
+
+export type WorkspaceVideoGenerationSettings = {
+  schemaVersion: 1;
+  policy: VideoGenerationPolicy;
+  fundingOptions: VideoGenerationFundingOption[];
+  availableModels: VideoGenerationModelCapability[];
+  capabilities: VideoGenerationCapabilities | null;
+};
+
+export type GeneratedVideoFacts = {
+  durationSeconds: number;
+  width: number;
+  height: number;
+  fps: number;
+  hasAudio: boolean;
+  videoCodec: "h264";
+  audioCodec: "aac" | null;
+};
+
+export type GeneratedVideoReceipt = {
+  type: "generated_video";
+  schemaVersion: 1;
+  operationId: string;
+  artifact: RetainedArtifactReference;
+  video: GeneratedVideoFacts;
+  sandboxPath: string;
+};
+
+export type VideoGenerationTerminalFailureStatus =
+  | "provider_failed"
+  | "retention_failed"
+  | "cancelled_before_submit"
+  | "outcome_unknown";
+
+export type MediaGenerationResult =
+  | {
+      type: "media_generation_result";
+      schemaVersion: 1;
+      status: "ready";
+      operationId: string;
+      receipt: GeneratedVideoReceipt;
+    }
+  | {
+      type: "media_generation_result";
+      schemaVersion: 1;
+      status: VideoGenerationTerminalFailureStatus;
+      operationId: string;
+      boundedPublicReason: string;
+    };
+
+export type VideoGenerationPublicStatus =
+  | "preparing"
+  | "prepared"
+  | "accepted"
+  | "provider_started"
+  | "retaining"
+  | "completed"
+  | VideoGenerationTerminalFailureStatus;
+
+export type VideoGenerationOperationSummary = {
+  schemaVersion: 1;
+  operationId: string;
+  modelId: string;
+  status: VideoGenerationPublicStatus;
+  createdAt: string;
+  updatedAt: string;
+  terminal: MediaGenerationResult | null;
+};
+
+/** Ephemeral source minted for native browser playback; never persist the URL. */
+export type VideoArtifactPlaybackSource = {
+  schemaVersion: 1;
+  artifactId: string;
+  url: string;
+  expiresAt: string;
+  contentType: "video/mp4";
+  sizeBytes: number;
+  sha256: string;
+  acceptRanges: "bytes";
+};
+
 export type RetainedArtifactContentOptions = {
   /** One RFC-style bytes range, for example `bytes=1048576-2097151`. */
   range?: string | undefined;
@@ -3470,6 +4113,25 @@ export type RetainedArtifactContent = {
   acceptRanges: "bytes";
 };
 
+export type RetainedArtifactDownloadOptions = {
+  signal?: AbortSignal | undefined;
+  /** Retry transient range failures; bounded to 0..3, default 2. */
+  maxRetries?: number | undefined;
+};
+
+export type RetainedScreenshotDownloadOptions = RetainedArtifactDownloadOptions;
+
+export type RetainedScreenshotDownload = {
+  metadata: RetainedArtifactMetadata;
+  /** Null when metadata truth says the screenshot is unavailable. */
+  bytes: Uint8Array | null;
+};
+
+export type RetainedArtifactDownload = {
+  artifact: RetainedArtifactReference;
+  bytes: Uint8Array;
+};
+
 export type CreateFileUploadRequest = {
   filename: string;
   contentType: string;
@@ -3505,6 +4167,8 @@ export type UploadFileInput = {
   contentType: string;
   data: FileUploadData;
   sha256?: string | undefined;
+  /** Optional deadline for the signed object-storage PUT. */
+  timeoutMs?: number | undefined;
 };
 
 // --- Documents -------------------------------------------------------------------
@@ -3811,6 +4475,49 @@ export type CapabilityPackVariableSetSpec = {
   required: boolean;
 };
 
+export type CapabilityPackComponentReference =
+  | {
+      key: string;
+      kind: "plugin";
+      pluginKey: string;
+      version: string;
+      manifestDigest: string;
+      required: boolean;
+    }
+  | {
+      key: string;
+      kind: "skill";
+      capabilityId: string;
+      contentSha256: string;
+      required: boolean;
+    }
+  | {
+      key: string;
+      kind: "integration";
+      capabilityId: string;
+      instanceKey: string;
+      revisionId: string;
+      contentSha256: string;
+      required: boolean;
+    }
+  | {
+      key: string;
+      kind: "feature";
+      capabilityId: string;
+      instanceKey: string;
+      featureKey: string;
+      bindingKey: string;
+      configDigest: string;
+      required: boolean;
+    };
+
+export type CapabilityPackRigRequirement = {
+  description?: string | undefined;
+  required: boolean;
+  rigId?: string | undefined;
+  requireVerified: boolean;
+};
+
 export type CapabilityPack = {
   id: string;
   name: string;
@@ -3825,6 +4532,8 @@ export type CapabilityPack = {
       }
     | undefined;
   skills: CapabilityPackSkill[];
+  components: CapabilityPackComponentReference[];
+  rig?: CapabilityPackRigRequirement | undefined;
   tools: ToolRef[];
   connectors: CapabilityPackConnector[];
   knowledge: CapabilityPackKnowledge[];
@@ -3854,6 +4563,52 @@ export type RegisterCapabilityPackRequest = {
         files: CapabilityPackSkillFile[];
       }[]
     | undefined;
+  components?:
+    | (
+        | {
+            key: string;
+            kind: "plugin";
+            pluginKey: string;
+            version: string;
+            manifestDigest: string;
+            required?: boolean | undefined;
+          }
+        | {
+            key: string;
+            kind: "skill";
+            capabilityId: string;
+            contentSha256: string;
+            required?: boolean | undefined;
+          }
+        | {
+            key: string;
+            kind: "integration";
+            capabilityId: string;
+            instanceKey: string;
+            revisionId: string;
+            contentSha256: string;
+            required?: boolean | undefined;
+          }
+        | {
+            key: string;
+            kind: "feature";
+            capabilityId: string;
+            instanceKey: string;
+            featureKey: string;
+            bindingKey: string;
+            configDigest: string;
+            required?: boolean | undefined;
+          }
+      )[]
+    | undefined;
+  rig?:
+    | {
+        description?: string | undefined;
+        required?: boolean | undefined;
+        rigId?: string | undefined;
+        requireVerified?: boolean | undefined;
+      }
+    | undefined;
   tools?: ToolRef[] | undefined;
   connectors?:
     | {
@@ -3905,7 +4660,7 @@ export type WorkspaceRegisteredPack = {
   updatedAt: string;
 };
 
-export type PackInstallationStatus = "active" | "disabled";
+export type PackInstallationStatus = "installing" | "active" | "needs_attention" | "disabled";
 
 export type PackInstallation = {
   id: string;
@@ -3913,6 +4668,11 @@ export type PackInstallation = {
   workspaceId: string;
   packId: string;
   status: PackInstallationStatus;
+  version: number;
+  manifestSnapshot: CapabilityPack | null;
+  manifestDigest: string | null;
+  selectedRigId: string | null;
+  installedBySubjectId: string | null;
   metadata: Record<string, unknown>;
   enabledAt: string;
   updatedAt: string;
@@ -3925,6 +4685,82 @@ export type EnablePackRequest = {
   metadata?: Record<string, unknown> | undefined;
 };
 
+export type PackComponentResolutionStatus = "ready" | "missing" | "mismatch";
+
+export type PackComponentResolution = {
+  key: string;
+  kind: "plugin" | "skill" | "integration" | "feature" | "inline_skill";
+  capabilityId: string;
+  required: boolean;
+  status: PackComponentResolutionStatus;
+  expectedDigest: string;
+  actualDigest: string | null;
+  resolvedId: string | null;
+  label: string;
+};
+
+export type PackRigResolution = {
+  required: boolean;
+  status: "not_required" | "ready" | "missing" | "mismatch" | "unverified";
+  requestedRigId: string | null;
+  rigId: string | null;
+  rigVersionId: string | null;
+  name: string | null;
+  image: string | null;
+};
+
+export type PreviewPackInstallationRequest = {
+  rigId?: string | undefined;
+  variableSetId?: string | undefined;
+};
+
+export type PackInstallationPreview = {
+  packId: string;
+  packVersion: string;
+  manifestDigest: string;
+  installationVersion: number | null;
+  action: "install" | "update" | "repair";
+  ready: boolean;
+  blockers: string[];
+  components: PackComponentResolution[];
+  rig: PackRigResolution;
+  variableSetId: string | null;
+  legacyInlineSkillCount: number;
+  legacySandboxImage: string | null;
+};
+
+export type InstallPackRequest = {
+  expectedManifestDigest: string;
+  expectedInstallationVersion?: number | undefined;
+  rigId?: string | undefined;
+  variableSetId?: string | undefined;
+  idempotencyKey: string;
+  metadata?: Record<string, unknown> | undefined;
+};
+
+export type PackUninstallPreview = {
+  packId: string;
+  installed: boolean;
+  installationVersion: number | null;
+  components: Array<{
+    key: string;
+    kind: "plugin" | "skill" | "integration" | "feature" | "inline_skill";
+    capabilityId: string;
+    retainedByOtherOwners: boolean;
+  }>;
+};
+
+export type UninstallPackRequest = {
+  expectedInstallationVersion: number;
+  idempotencyKey: string;
+};
+
+export type UninstallPackResult = {
+  packId: string;
+  status: "not_installed" | "uninstalled";
+  retainedComponents: string[];
+};
+
 export type ListPacksResponse = {
   packs: CapabilityPack[];
   installations: PackInstallation[];
@@ -3953,6 +4789,34 @@ export type CapabilityCatalogAuthKind = "oauth2" | "api_key" | "none" | "unknown
 
 export type CapabilityCatalogTier = "verified" | "community";
 
+export type CapabilityLifecycleStatus =
+  | "available"
+  | "installed"
+  | "connected"
+  | "ready"
+  | "needs_attention"
+  | "unavailable"
+  | "managed";
+
+export type CapabilityReadiness = "ready" | "setup_required" | "attention" | "unavailable";
+
+export type CapabilityAction =
+  | "install"
+  | "connect"
+  | "configure"
+  | "update"
+  | "repair"
+  | "disconnect"
+  | "uninstall"
+  | "inspect";
+
+export type CapabilityLifecycle = {
+  status: CapabilityLifecycleStatus;
+  readiness: CapabilityReadiness;
+  detail: string | null;
+  managedBy: "deployment" | "platform" | "workspace" | null;
+};
+
 export type CapabilityRuntime = {
   available: boolean;
   mcpServerId?: string | undefined;
@@ -3999,7 +4863,11 @@ export type CapabilityCatalogItem = {
   staleAt: string | null;
   tools: ToolRef[];
   runtime: CapabilityRuntime;
+  lifecycle: CapabilityLifecycle;
+  actions: CapabilityAction[];
+  /** @deprecated Use lifecycle and actions. */
   enabled: boolean;
+  /** @deprecated Use lifecycle.detail. */
   enabledReason: string | null;
   /** The connection backing this enabled installation, or null when none is involved. */
   connectionRef: {
@@ -4072,6 +4940,447 @@ export type DiscoverMcpCapabilitiesResponse = {
   sourceUrl: string;
 };
 
+export type SkillImportSource = "github" | "skills_sh";
+
+export type PreviewSkillImportRequest = {
+  url: string;
+};
+
+export type SkillImportFileSummary = {
+  path: string;
+  byteSize: number;
+  contentSha256: string;
+};
+
+export type SkillImportPreview = {
+  source: SkillImportSource;
+  sourceUrl: string;
+  repositoryUrl: string;
+  owner: string;
+  repository: string;
+  sourcePath: string;
+  sourceCommit: string;
+  name: string;
+  description: string;
+  contentSha256: string;
+  totalBytes: number;
+  files: SkillImportFileSummary[];
+  warnings: string[];
+  installed: boolean;
+  installationVersion: number | null;
+};
+
+export type InstallSkillRequest = {
+  url: string;
+  expectedSourceCommit: string;
+  expectedContentSha256: string;
+  expectedInstallationVersion?: number | undefined;
+};
+
+export type InstalledSkill = {
+  capabilityId: string;
+  pluginId: string;
+  pluginVersionId: string;
+  facetId: string;
+  pluginInstallationId: string;
+  facetInstallationId: string;
+  installationVersion: number;
+  source: SkillImportSource;
+  sourceUrl: string;
+  sourceCommit: string;
+  contentSha256: string;
+  name: string;
+  status: "installed";
+};
+
+export type CapabilityComponentOwner = {
+  kind: "direct" | "plugin" | "pack" | "migration";
+  id: string;
+  removable: boolean;
+};
+
+export type SkillUninstallPreview = {
+  capabilityId: string;
+  installed: boolean;
+  installationVersion: number | null;
+  directOwner: CapabilityComponentOwner | null;
+  remainingOwners: CapabilityComponentOwner[];
+  removesRuntimeSkill: boolean;
+};
+
+export type UninstallSkillRequest = {
+  expectedInstallationVersion: number;
+};
+
+export type UninstallSkillResult = {
+  capabilityId: string;
+  status: "not_installed" | "uninstalled" | "retained_by_other_owners";
+  remainingOwners: CapabilityComponentOwner[];
+};
+
+export type ApiIntegrationProtocol = "openapi" | "graphql";
+
+export type IntegrationFeatureKind =
+  | "tools"
+  | "knowledge_source"
+  | "inbound_trigger"
+  | "delivery_destination"
+  | "identity_link";
+
+export type IntegrationFeatureStatus = "active" | "paused" | "needs_attention" | "disabled";
+
+export type IntegrationFeatureDefinitionSummary = {
+  featureKey: string;
+  kind: Exclude<IntegrationFeatureKind, "tools">;
+  configSchema: Record<string, unknown>;
+  capabilities: Record<string, unknown>;
+};
+
+export type IntegrationFeatureBindingSummary = {
+  id: string;
+  featureKey: string;
+  kind: Exclude<IntegrationFeatureKind, "tools">;
+  bindingKey: string;
+  displayName: string;
+  connectionId: string | null;
+  status: IntegrationFeatureStatus;
+  config: Record<string, unknown>;
+  version: number;
+  hasCursor: boolean;
+  lastSuccessAt: string | null;
+  lastErrorCode: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type IntegrationInstanceFeaturesResponse = {
+  capabilityId: string;
+  instanceKey: string;
+  providerDomain: string;
+  connectionId: string | null;
+  features: {
+    definition: IntegrationFeatureDefinitionSummary;
+    binding: IntegrationFeatureBindingSummary | null;
+  }[];
+};
+
+export type UpsertIntegrationFeatureRequest = {
+  displayName: string;
+  config?: Record<string, unknown> | undefined;
+  expectedVersion?: number | undefined;
+  idempotencyKey: string;
+};
+
+export type MutateIntegrationFeatureRequest = {
+  expectedVersion: number;
+  idempotencyKey: string;
+};
+
+export type IntegrationFeatureMutationResult = {
+  capabilityId: string;
+  instanceKey: string;
+  featureKey: string;
+  status: "configured" | "paused" | "active";
+  binding: IntegrationFeatureBindingSummary;
+};
+
+export type IntegrationFeatureRemovalResult = {
+  capabilityId: string;
+  instanceKey: string;
+  featureKey: string;
+  status: "not_configured" | "removed" | "retained_by_other_owners";
+  binding: IntegrationFeatureBindingSummary | null;
+  remainingOwners: CapabilityComponentOwner[];
+};
+
+export type ApiIntegrationPresetSummary = {
+  id: string;
+  name: string;
+  summary: string;
+  family: "google" | "microsoft";
+  protocol: "openapi";
+  providerDomain: string;
+  scopes: string[];
+  features: IntegrationFeatureDefinitionSummary[];
+};
+
+export type ListApiIntegrationPresetsResponse = {
+  presets: ApiIntegrationPresetSummary[];
+};
+
+export type ApiIntegrationSource =
+  | { kind: "preset"; presetId: string }
+  | { kind: "openapi"; url: string; baseUrl?: string | undefined }
+  | { kind: "graphql"; endpoint: string; name?: string | undefined }
+  | { kind: "auto"; url: string; baseUrl?: string | undefined };
+
+export type PreviewApiIntegrationRequest = {
+  source: ApiIntegrationSource;
+  connectionId?: string | undefined;
+  ownership?: ConnectionOwnership | undefined;
+};
+
+export type ApiIntegrationOAuthStartRequest = {
+  presetId: string;
+  ownership?: ConnectionOwnership | undefined;
+  connectionId?: string | undefined;
+  returnPath?: string | undefined;
+};
+
+export type ApiIntegrationAuthPreview =
+  | { kind: "none" }
+  | { kind: "oauth2"; providerDomain: string; scopes: string[] }
+  | {
+      kind: "api_key";
+      providerDomain: string;
+      carrier: "header" | "query" | "cookie";
+      name: string;
+    }
+  | { kind: "http"; providerDomain: string; scheme: string };
+
+export type ApiIntegrationToolPreview = {
+  id: string;
+  operationKey: string;
+  name: string;
+  description: string;
+  safety: "read" | "write" | "destructive";
+  approvalMode: "never" | "ask";
+  deprecated: boolean;
+};
+
+export type ApiIntegrationPreview = {
+  source: ApiIntegrationSource;
+  presetId: string | null;
+  protocol: ApiIntegrationProtocol;
+  integrationId: string;
+  capabilityId: string;
+  pluginKey: string;
+  serverId: string;
+  name: string;
+  description: string | null;
+  provider: string | null;
+  providerDomain: string;
+  baseUrl: string;
+  sourceUrl: string | null;
+  revisionId: string;
+  contentSha256: string;
+  auth: ApiIntegrationAuthPreview;
+  connectionId: string | null;
+  connectionOwnership: ConnectionOwnership | null;
+  tools: ApiIntegrationToolPreview[];
+  warnings: string[];
+};
+
+export type InstallApiIntegrationRequest = {
+  source: ApiIntegrationSource;
+  expectedRevisionId: string;
+  expectedContentSha256: string;
+  connectionId?: string | undefined;
+  ownership?: ConnectionOwnership | undefined;
+  instanceKey?: string | undefined;
+  displayName?: string | undefined;
+  expectedInstanceVersion?: number | undefined;
+  allowedTools?: string[] | undefined;
+};
+
+export type InstalledApiIntegration = {
+  capabilityId: string;
+  pluginId: string;
+  pluginVersionId: string;
+  integrationFacetId: string;
+  apiFacetId: string;
+  pluginInstallationId: string;
+  integrationFacetInstallationId: string;
+  apiFacetInstallationId: string;
+  installationVersion: number;
+  instanceId: string;
+  instanceKey: string;
+  displayName: string;
+  instanceVersion: number;
+  revisionId: string;
+  serverId: string;
+  status: "installed";
+};
+
+export type ApiIntegrationInstallationSummary = {
+  capabilityId: string;
+  pluginKey: string;
+  installationVersion: number;
+  instanceId: string;
+  instanceKey: string;
+  displayName: string;
+  instanceVersion: number;
+  serverId: string;
+  name: string;
+  description: string | null;
+  protocol: ApiIntegrationProtocol;
+  presetId: string | null;
+  providerDomain: string;
+  baseUrl: string;
+  sourceUrl: string | null;
+  connected: boolean;
+  requiresConnection: boolean;
+  connectionId: string | null;
+  ownership: "workspace" | "personal" | "none";
+  allowedTools: string[];
+  toolCount: number;
+  approvalRequiredToolCount: number;
+  revisionId: string;
+  contentSha256: string;
+};
+
+export type ListApiIntegrationsResponse = {
+  integrations: ApiIntegrationInstallationSummary[];
+};
+
+export type ApiIntegrationUninstallPreview = {
+  capabilityId: string;
+  instanceKey: string;
+  displayName: string | null;
+  installed: boolean;
+  installationVersion: number | null;
+  instanceVersion: number | null;
+  directOwner: CapabilityComponentOwner | null;
+  remainingOwners: CapabilityComponentOwner[];
+  removesRuntimeIntegration: boolean;
+  removesDefinition: boolean;
+};
+
+export type UninstallApiIntegrationRequest = {
+  expectedInstallationVersion: number;
+  expectedInstanceVersion: number;
+};
+
+export type UninstallApiIntegrationResult = {
+  capabilityId: string;
+  instanceKey: string;
+  status: "not_installed" | "uninstalled" | "retained_by_other_owners";
+  remainingOwners: CapabilityComponentOwner[];
+  definitionStatus: "retained" | "disabled";
+};
+
+export type PluginManifestComponent =
+  | { key: string; kind: "skill"; url: string }
+  | { key: string; kind: "integration"; source: ApiIntegrationSource }
+  | { key: string; kind: "mcp"; serverId: string };
+
+export type PluginManifest = {
+  schemaVersion: 1;
+  pluginKey: string;
+  version: string;
+  name: string;
+  description: string;
+  category: string;
+  tags: string[];
+  components: PluginManifestComponent[];
+};
+
+export type PluginComponentBinding = {
+  connectionId?: string | undefined;
+  instanceKey?: string | undefined;
+  displayName?: string | undefined;
+};
+
+export type PreviewPluginRequest = {
+  url: string;
+  bindings?: Record<string, PluginComponentBinding> | undefined;
+};
+
+export type PluginComponentPreview = {
+  key: string;
+  kind: "skill" | "integration" | "mcp";
+  name: string;
+  capabilityId: string;
+  digest: string;
+  connectionRequired: boolean;
+  connectionId: string | null;
+  instanceKey: string | null;
+  displayName: string | null;
+  facts: Record<string, unknown>;
+};
+
+export type PluginUpdateDiff = {
+  fromVersion: string | null;
+  toVersion: string;
+  added: string[];
+  removed: string[];
+  changed: string[];
+  unchanged: string[];
+};
+
+export type PluginPreview = {
+  sourceUrl: string;
+  manifest: PluginManifest;
+  manifestDigest: string;
+  installed: boolean;
+  installationVersion: number | null;
+  components: PluginComponentPreview[];
+  diff: PluginUpdateDiff;
+};
+
+export type InstallPluginRequest = {
+  url: string;
+  expectedManifestDigest: string;
+  expectedComponents: Array<{ key: string; digest: string }>;
+  bindings?: Record<string, PluginComponentBinding> | undefined;
+  idempotencyKey: string;
+  expectedInstallationVersion?: number | undefined;
+};
+
+export type InstalledPlugin = {
+  pluginKey: string;
+  version: string;
+  pluginId: string;
+  pluginVersionId: string;
+  pluginInstallationId: string;
+  installationVersion: number;
+  componentCount: number;
+  status: "installed";
+};
+
+export type PluginInstallationSummary = {
+  pluginKey: string;
+  version: string;
+  name: string;
+  description: string;
+  category: string;
+  tags: string[];
+  sourceUrl: string | null;
+  manifestDigest: string;
+  installationVersion: number;
+  componentCount: number;
+  status: "active" | "needs_attention";
+  installedAt: string;
+  updatedAt: string;
+};
+
+export type ListInstalledPluginsResponse = {
+  plugins: PluginInstallationSummary[];
+};
+
+export type PluginUninstallPreview = {
+  pluginKey: string;
+  installed: boolean;
+  version: string | null;
+  installationVersion: number | null;
+  components: Array<{
+    capabilityId: string;
+    kind: "skill" | "integration" | "mcp";
+    retainedByOtherOwners: boolean;
+  }>;
+};
+
+export type UninstallPluginRequest = {
+  expectedInstallationVersion: number;
+  idempotencyKey: string;
+};
+
+export type UninstallPluginResult = {
+  pluginKey: string;
+  status: "not_installed" | "uninstalled";
+  retainedComponents: string[];
+};
+
 // --- GitHub ---------------------------------------------------------------------
 
 export type GitHubRepository = {
@@ -4168,6 +5477,10 @@ export const KNOWN_USAGE_EVENT_TYPES = [
   "file.deleted",
   "document.indexed",
   "scheduled_task.fired",
+  "knowledge_source_sync.fired",
+  "knowledge_source_sync.completed",
+  "knowledge_source_sync.items",
+  "knowledge_source_sync.bytes",
   "api_key.request",
   // sandbox warm-time metering (P2.1) — mirrors contracts UsageEventType.
   "sandbox.warm_seconds",
@@ -4213,6 +5526,8 @@ export type InsightsRange = "today" | "week" | "month" | "ytd";
 
 export type InsightsBillingPath = "opengeni_credits" | "external";
 
+export type InsightsPricingSource = "configured_list_price" | "gateway_reported";
+
 export type InsightsModelUsageRow = {
   id: string;
   model: string;
@@ -4222,17 +5537,32 @@ export type InsightsModelUsageRow = {
   inputTokens: number;
   outputTokens: number;
   cachedTokens: number;
+  cacheInputTokens: number;
   cacheWriteTokens: number;
   reasoningTokens: number;
+  totalTokens: number;
+  tokenKnownCalls: number;
+  cacheKnownCalls: number;
   creditUsd: number;
+  estimatedProviderUsd: number;
+  estimatedProviderCostKnownCalls: number;
 };
 
 export type InsightsSeriesPoint = {
   label: string;
   modelCostUsd: number;
+  estimatedProviderUsd: number;
+  estimatedProviderCostKnownCalls: number;
   warmSeconds: number;
   inputTokens: number;
+  outputTokens: number;
   cachedTokens: number;
+  cacheInputTokens: number;
+  cacheWriteTokens: number;
+  reasoningTokens: number;
+  totalTokens: number;
+  tokenKnownCalls: number;
+  cacheKnownCalls: number;
   cacheHitPct: number;
   calls: number;
 };
@@ -4252,9 +5582,12 @@ export type InsightsSpendDriver = {
   groupBy: "root_session" | "schedule";
   label: string;
   creditUsd: number;
+  estimatedProviderUsd: number;
+  estimatedProviderCostKnownCalls: number;
   tokens: number;
   cacheHitPct: number;
   pctOfCreditUsd: number;
+  pctOfTokens: number;
   deltaUsdVsPrior: number;
 };
 
@@ -4294,17 +5627,44 @@ export type InsightsScheduleRow = {
   name: string;
   fires: number;
   creditUsd: number | null;
+  estimatedProviderUsd: number | null;
+  estimatedProviderCostKnownCalls: number | null;
   tokens: number | null;
   cacheHitPct: number | null;
   billing: InsightsBillingPath | null;
 };
 
+export type InsightsModelCallRow = {
+  id: string;
+  occurredAt: string;
+  recordedAt: string;
+  sessionId: string;
+  sessionTitle: string;
+  turnId: string;
+  provider: string;
+  providerApi: string;
+  model: string;
+  billing: InsightsBillingPath;
+  inputTokens: number | null;
+  outputTokens: number | null;
+  cachedTokens: number | null;
+  cacheWriteTokens: number | null;
+  reasoningTokens: number | null;
+  totalTokens: number | null;
+  creditUsd: number;
+  estimatedProviderUsd: number | null;
+  pricingSource: InsightsPricingSource | null;
+};
+
 export type WorkspaceInsightsSnapshot = {
   range: InsightsRange;
   rangeLabel: string;
   priorLabel: string;
   seriesLabel: string;
   cacheSeriesLabel: string;
+  windowStart: string;
+  windowEnd: string;
+  generatedAt: string;
   timezone: "UTC";
   models: InsightsModelUsageRow[];
   facets: InsightsModelFacet[];
@@ -4312,6 +5672,7 @@ export type WorkspaceInsightsSnapshot = {
   depth: InsightsDepthBucket[];
   drivers: InsightsSpendDriver[];
   schedules: InsightsScheduleRow[];
+  recentCalls: InsightsModelCallRow[];
   warmSeconds: number;
   priorWarmSeconds: number;
   warmGroups: InsightsWarmGroupRow[];
@@ -4323,7 +5684,13 @@ export type WorkspaceInsightsSnapshot = {
   priorWorkspaceCreditUsd: number;
   creditUsd: number;
   priorCreditUsd: number;
+  estimatedProviderUsd: number;
+  priorEstimatedProviderUsd: number;
+  estimatedProviderCostKnownCalls: number;
+  priorEstimatedProviderCostKnownCalls: number;
+  modelCalls: number;
   priorInputTokens: number;
+  priorTotalTokens: number;
   priorCacheHitPct: number;
   priorCalls: number;
   goalsActive: number;
@@ -4369,6 +5736,7 @@ export type UserMessageEventInput = {
   clientEventId?: string | undefined;
   payload: {
     text: string;
+    annotations?: SubmittedTimelineAnnotation[] | undefined;
     turnInstructions?: string | undefined;
     resources?: ResourceRef[] | undefined;
     model?: string | undefined;
@@ -4478,6 +5846,34 @@ export type MachineMetricsSeriesResponse = {
   samples: MetricSample[];
 };
 
+/** POST /v1/workspaces/:ws/enrollments/:id/revoke body. */
+export type RemoveEnrollmentRequest = {
+  expectedUpdatedAt?: string;
+  idempotencyKey?: string;
+};
+
+/** Typed removal/revocation outcome. Blocked outcomes preserve the exact
+ * dependency and the action needed to make removal safe. */
+export type RemoveEnrollmentResponse = {
+  revoked: boolean;
+  outcome: "removed" | "already_removed" | "blocked";
+  enrollmentId: string;
+  machineName: string | null;
+  lastSeenAt: string | null;
+  revokedAt: string | null;
+  code:
+    | "active_route"
+    | "active_commands"
+    | "machine_home"
+    | "active_lease"
+    | "recovery_pending"
+    | "not_selfhosted"
+    | null;
+  message: string;
+  action: string;
+  dependentSessions: Array<{ id: string; title: string | null }>;
+};
+
 /** POST /v1/workspaces/:ws/sessions/:sessionId/active-sandbox — swap a session's
  *  active sandbox. `target` is a `MachineView.sandboxId`, or "session"/"default"
  *  to swap back to the session's own group box. */
@@ -4508,8 +5904,9 @@ export type SwapActiveSandboxResponse = {
 
 // ── Self-hosted enrollment UX (design 11) ────────────────────────────────────
 // Hand-written mirrors of the `@opengeni/contracts` enrollment-UX request/response
-// shapes (the SDK keeps zero runtime deps). The click-Grant approve-page
-// lookup/deny + the headless enroll-token mint/exchange.
+// shapes. They remain type-only so ordinary SDK entries do not reach the contracts
+// runtime. The click-Grant approve-page lookup/deny + the headless enroll-token
+// mint/exchange.
 
 /** Mirror of `@opengeni/contracts` EnrollmentOs. */
 export type EnrollmentOs = "linux" | "macos" | "windows";