@opengeni/sdk 0.52.1 → 1.0.0

package/src/knowledge.ts

@@ -0,0 +1,72 @@
+export type {
+  AgentLearningMode,
+  AgentLearningCategory,
+  AgentLearningDefaults,
+  AgentLearningOverrides,
+  AgentLearningContext,
+  AgentLearningOverridePatch,
+  AgentLearningSettingsRecord,
+  AgentLearningOverrideRecord,
+  SaveAgentLearningSettingsRequest,
+  KnowledgeFilePreparationResult,
+  KnowledgeSavePreparationRequest,
+  KnowledgeSavePreparationResponse,
+  KnowledgeOriginalFileDownload,
+  KnowledgeEntryKind,
+  KnowledgeEntryScope,
+  KnowledgeIndexStatus,
+  KnowledgeEntryContent,
+  KnowledgeEntrySource,
+  KnowledgeEntryEvidence,
+  KnowledgeEntryRelationship,
+  KnowledgeEntryRecord,
+  KnowledgeEntrySummary,
+  KnowledgeEntrySaveRequest,
+  KnowledgeEntryReviewRequest,
+  KnowledgeEntryBatchReviewRequest,
+  KnowledgeEntryRestoreRequest,
+  KnowledgeEntryWriteReceipt,
+  KnowledgeEntryListRequest,
+  KnowledgeEntryListResponse,
+  KnowledgeReviewBatch,
+  KnowledgeReviewBatchListRequest,
+  KnowledgeReviewBatchListResponse,
+  AgentInstructionReviewRequest,
+  AgentInstructionReceipt,
+  AgentInstructionReviewItem,
+  AgentInstructionReviewListResponse,
+} from "@opengeni/contracts";
+
+import type { OpenGeniClient } from "./client";
+import type {
+  KnowledgeSavePreparationRequest,
+  KnowledgeSavePreparationResponse,
+  KnowledgeFilePreparationResult,
+} from "@opengeni/contracts";
+
+/** Agent-only source preparation is a focused transport surface, outside the browser client. */
+export async function prepareKnowledgeFile(
+  client: Pick<OpenGeniClient, "requestJson">,
+  workspaceId: string,
+  fileId: string,
+  purpose?: "evidence" | "reference",
+): Promise<KnowledgeFilePreparationResult> {
+  return client.requestJson(
+    "POST",
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/knowledge/files/${encodeURIComponent(fileId)}/prepare`,
+    purpose ? { purpose } : undefined,
+  );
+}
+
+/** Read-only collection/duplicate discovery for a live selected agent or human Knowledge reviewer. */
+export async function prepareKnowledgeSave(
+  client: Pick<OpenGeniClient, "requestJson">,
+  workspaceId: string,
+  request: KnowledgeSavePreparationRequest,
+): Promise<KnowledgeSavePreparationResponse> {
+  return client.requestJson(
+    "POST",
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/knowledge/entries/prepare-save`,
+    request,
+  );
+}

package/src/message-links.ts

@@ -0,0 +1,178 @@
+/**
+ * Links an agent writes into chat Markdown that point at OpenGeni-owned objects.
+ *
+ * Agents write these forms (tool receipts and bundled Skills teach them):
+ *
+ * - `artifact:<file uuid>` — a retained workspace file (exports, published files, images).
+ * - `sandbox:<path>[:<line>]` — a file in the session's sandbox or Connected Machine.
+ * - `/workspaces/<ws>/artifacts/editable/<32-hex id>` — a live editable document,
+ *   workbook, or presentation.
+ * - `/workspaces/<ws>/artifacts/<uuid>` — a saved Site / published HTML artifact.
+ * - `/workspaces/<ws>/artifacts/files/<uuid>` — a retained file (console path form).
+ *
+ * None of them is a URL a browser can navigate on its own: the `/workspaces/...`
+ * forms are OpenGeni console routes, so inside another product they resolve
+ * against that product's origin and 404. Parse them with {@link parseOpenGeniLink}
+ * and route each target to the host's own UI (download, panel, page).
+ */
+export type OpenGeniLinkTarget =
+  | { kind: "file"; fileId: string; workspaceId: string | null; fromSession?: string }
+  | { kind: "editable-artifact"; artifactId: string; workspaceId: string; fromSession?: string }
+  | { kind: "site"; artifactId: string; workspaceId: string; fromSession?: string }
+  | { kind: "sandbox-file"; path: string; line: number | null };
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+const EDITABLE_ID = /^[0-9a-f]{32}$/iu;
+const WORKSPACE_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/u;
+const SANDBOX_SCHEME = "sandbox:";
+const LEGACY_WORKSPACE_PREFIX = "/workspace/";
+const TRAILING_LINE = /:([0-9]+)$/u;
+const TRAILING_INVALID_LINE = /:-(?:[0-9]+)$|:[0-9]+-[0-9]+$/u;
+const CONTROL_CHARACTER = /[\u0000-\u001f\u007f]/u;
+
+/** Application scheme names are case-insensitive, unlike their payloads. */
+export function openGeniLinkScheme(href: string | undefined): "artifact" | "sandbox" | null {
+  const scheme = /^([a-z]+):/iu.exec(href ?? "")?.[1]?.toLowerCase();
+  return scheme === "artifact" || scheme === "sandbox" ? scheme : null;
+}
+
+/** Reserved references must never fall back to navigation on a host origin. */
+export function isReservedOpenGeniLink(href: string | undefined): boolean {
+  if (!href) return false;
+  if (openGeniLinkScheme(href) || href.startsWith(LEGACY_WORKSPACE_PREFIX)) return true;
+  // Decoding is for reservation only: encoded variants are not valid targets.
+  try {
+    return /^\/workspaces\/[^/]+\/artifacts(?:\/|[?#]|$)/u.test(decodeURIComponent(href));
+  } catch {
+    return /^\/workspaces\/[^/]+\/artifacts/u.test(href);
+  }
+}
+
+/**
+ * Parse an OpenGeni `sandbox:` href (plus the historical bare `/workspace/...`
+ * form). The decoded path is intentionally opaque: target selection, path
+ * policy, and filesystem authority belong to the session-aware host.
+ */
+export function parseSandboxLink(
+  href: string | undefined,
+): { path: string; line: number | null } | null {
+  if (!href) return null;
+  const encodedLocation =
+    openGeniLinkScheme(href) === "sandbox"
+      ? href.slice(SANDBOX_SCHEME.length)
+      : href.startsWith(LEGACY_WORKSPACE_PREFIX)
+        ? href
+        : null;
+  if (!encodedLocation || encodedLocation.includes("?") || encodedLocation.includes("#")) {
+    return null;
+  }
+  if (TRAILING_INVALID_LINE.test(encodedLocation)) return null;
+  const lineMatch = TRAILING_LINE.exec(encodedLocation);
+  const encodedPath = lineMatch ? encodedLocation.slice(0, -lineMatch[0].length) : encodedLocation;
+  const line = lineMatch?.[1] ? Number(lineMatch[1]) : null;
+  if (line !== null && (!Number.isSafeInteger(line) || line < 1)) return null;
+  if (!encodedPath) return null;
+  try {
+    const path = decodeURIComponent(encodedPath);
+    return path && !CONTROL_CHARACTER.test(path) ? { path, line } : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Return the retained-file id of an exact `artifact:<uuid>` reference. */
+export function parseRetainedFileReference(href: string | undefined): string | null {
+  if (openGeniLinkScheme(href) !== "artifact") return null;
+  if (!href) return null;
+  const id = href.slice("artifact:".length);
+  return UUID.test(id) ? id.toLowerCase() : null;
+}
+
+/**
+ * Classify an agent-authored Markdown href. Returns `null` for ordinary links
+ * (`https://…`, `mailto:`, relative host links), which render as-is.
+ *
+ * Only root-relative console paths are recognized; an absolute URL is always an
+ * ordinary link, so a host's own `https://` routes are never reinterpreted.
+ * A validated `?fromSession=<uuid>` return hint is preserved.
+ */
+export function parseOpenGeniLink(href: string | undefined): OpenGeniLinkTarget | null {
+  if (!href) return null;
+  const fileId = parseRetainedFileReference(href);
+  if (fileId) return { kind: "file", fileId, workspaceId: null };
+  if (openGeniLinkScheme(href) === "sandbox" || href.startsWith(LEGACY_WORKSPACE_PREFIX)) {
+    const location = parseSandboxLink(href);
+    return location ? { kind: "sandbox-file", ...location } : null;
+  }
+  if (!href.startsWith("/workspaces/") || href.includes("#")) return null;
+  const separator = href.indexOf("?");
+  const pathname = separator < 0 ? href : href.slice(0, separator);
+  const search = separator < 0 ? undefined : href.slice(separator + 1);
+  let fromSession: string | undefined;
+  if (search !== undefined) {
+    const params = new URLSearchParams(search);
+    const keys = [...params.keys()];
+    if (keys.some((key) => key !== "fromSession") || keys.length > 1) return null;
+    if (!UUID.test(params.get("fromSession") ?? "")) return null;
+    fromSession = params.get("fromSession")!.toLowerCase();
+  }
+  const parts = pathname.split("/");
+  const workspaceId = parts[2] ?? "";
+  if (parts[1] !== "workspaces" || parts[3] !== "artifacts" || !WORKSPACE_SEGMENT.test(workspaceId))
+    return null;
+  if (parts.length === 6 && parts[4] === "editable" && EDITABLE_ID.test(parts[5] ?? "")) {
+    return {
+      kind: "editable-artifact",
+      artifactId: parts[5]!.toLowerCase(),
+      workspaceId,
+      ...(fromSession ? { fromSession } : {}),
+    };
+  }
+  if (parts.length === 6 && parts[4] === "files" && UUID.test(parts[5] ?? "")) {
+    return {
+      kind: "file",
+      fileId: parts[5]!.toLowerCase(),
+      workspaceId,
+      ...(fromSession ? { fromSession } : {}),
+    };
+  }
+  if (parts.length === 5 && UUID.test(parts[4] ?? "")) {
+    return {
+      kind: "site",
+      artifactId: parts[4]!.toLowerCase(),
+      workspaceId,
+      ...(fromSession ? { fromSession } : {}),
+    };
+  }
+  return null;
+}
+
+/** The OpenGeni console route for a target (the form agents write). */
+export function openGeniConsolePath(
+  target: OpenGeniLinkTarget,
+  workspaceId: string,
+): string | null {
+  const workspace = encodeURIComponent(
+    target.kind === "sandbox-file" ? workspaceId : (target.workspaceId ?? workspaceId),
+  );
+  const search =
+    target.kind !== "sandbox-file" && target.fromSession && UUID.test(target.fromSession)
+      ? `?fromSession=${encodeURIComponent(target.fromSession)}`
+      : "";
+  switch (target.kind) {
+    case "file":
+      return `/workspaces/${workspace}/artifacts/files/${target.fileId}${search}`;
+    case "editable-artifact":
+      return `/workspaces/${workspace}/artifacts/editable/${target.artifactId}${search}`;
+    case "site":
+      return `/workspaces/${workspace}/artifacts/${target.artifactId}${search}`;
+    case "sandbox-file":
+      return null;
+  }
+}
+
+/**
+ * Request header naming the session an embedded artifact read belongs to.
+ * `createSessionProxyHandler` only serves artifacts OpenGeni lists for it.
+ */
+export const SESSION_SCOPE_HEADER = "x-opengeni-session-id";

package/src/model-context.ts

@@ -0,0 +1,112 @@
+export type ModelContextInstructionLayerId =
+  | "operational_contract"
+  | "persona_and_core"
+  | "workspace_governance"
+  | "session_instructions"
+  | "workspace_memory"
+  | "skill_catalog"
+  | "codemode"
+  | "code_search"
+  | "git_bindings"
+  | "builtin_skills"
+  | "genesis_title"
+  | "sdk_capability_instructions"
+  | "sandbox_preamble"
+  | "sandbox_filesystem"
+  | "sent_system_instructions"
+  | "identity";
+
+/** Sections of a modular operational contract, in composition order. */
+export type AgentPromptModuleId =
+  | "base_behavior"
+  | "runtime_mechanics"
+  | "renderer_markdown"
+  | "sandbox"
+  | "connected_machine"
+  | "repositories"
+  | "workspace_environment"
+  | "rig"
+  | "artifacts"
+  | "media"
+  | "goals"
+  | "subagents"
+  | "knowledge"
+  | "skills"
+  | "admin"
+  | "attachments";
+
+export type ModelContextInstructionModule = {
+  id: AgentPromptModuleId;
+  chars: number;
+};
+
+export type ModelContextInstructionLayer = {
+  id: ModelContextInstructionLayerId;
+  title: string;
+  content: string;
+  utf8Bytes: number;
+  estimatedTokens: number;
+  /** Present on the operational contract of sessions with an agent configuration. */
+  modules?: ModelContextInstructionModule[] | undefined;
+};
+
+export type ModelContextToolVisibility = "eager" | "searchable";
+
+export type ModelContextTool = {
+  name: string;
+  type: string;
+  visibility: ModelContextToolVisibility;
+  description?: string | undefined;
+  namespace?: string | undefined;
+  schema?: unknown | undefined;
+  utf8Bytes: number;
+  estimatedTokens: number;
+};
+
+export type ModelContextSkillKind = "preference_descriptor" | "runtime_skill" | "native_tool_skill";
+
+export type ModelContextSkill = {
+  kind: ModelContextSkillKind;
+  name: string;
+  description: string;
+  source?: string | undefined;
+  path?: string | undefined;
+};
+
+export type ModelContextTokenCounts = {
+  instructions: number;
+  tools: number;
+  prefix: number;
+};
+
+export type ModelContextSnapshot = {
+  providerRequest?:
+    | {
+        provider: string;
+        body: string | null;
+        unavailableReason?: string | undefined;
+        parts: {
+          key: string;
+          estimatedTokens: number | null;
+          utf8Bytes: number;
+          itemEstimatedTokens?: (number | null)[] | undefined;
+        }[];
+      }
+    | undefined;
+  version: 1;
+  capturedAt: string;
+  source: "model_request";
+  requestIndex: number;
+  instructions: string;
+  layers: ModelContextInstructionLayer[];
+  tools: ModelContextTool[];
+  skills: ModelContextSkill[];
+  tokens: ModelContextTokenCounts;
+};
+
+export type SessionModelContextResponse = {
+  sessionId: string;
+  attemptId: string | null;
+  turnId: string | null;
+  snapshot: ModelContextSnapshot | null;
+};

package/src/model-display.ts

@@ -0,0 +1,10 @@
+/** One clean model name and maker for every surface outside model settings. */
+export {
+  humanizeModelSlug,
+  isRawModelLabel,
+  modelDisplayName,
+  modelSlug,
+  modelVendor,
+  type ModelDisplayInput,
+  type ModelVendor,
+} from "@opengeni/contracts/model-display";

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/organization-integration-policy.ts

@@ -0,0 +1,54 @@
+import type { OpenGeniClient } from "./client";
+
+export type OrganizationIntegrationPolicy = {
+  mode: "unrestricted" | "restricted";
+  allowedIntegrationKeys: string[];
+  revision: number;
+};
+
+export type UpdateOrganizationIntegrationPolicyRequest = {
+  mode: "unrestricted" | "restricted";
+  allowedIntegrationKeys: string[];
+  expectedRevision: number;
+  operationId: string;
+};
+
+type PolicyClient = Pick<OpenGeniClient, "requestJson">;
+
+export type OrganizationIntegrationCatalog = {
+  integrations: Array<{ key: string; label: string; kind: "curated" | "custom" }>;
+};
+
+/** Discover stable policy identities; integrations must not guess provider identifiers. */
+export async function getOrganizationIntegrationCatalog(
+  client: PolicyClient,
+  organizationId: string,
+): Promise<OrganizationIntegrationCatalog> {
+  return client.requestJson(
+    "GET",
+    `/v1/organizations/${encodeURIComponent(organizationId)}/integration-policy/catalog`,
+  );
+}
+
+export async function getOrganizationIntegrationPolicy(
+  client: PolicyClient,
+  organizationId: string,
+): Promise<OrganizationIntegrationPolicy> {
+  return client.requestJson(
+    "GET",
+    `/v1/organizations/${encodeURIComponent(organizationId)}/integration-policy`,
+  );
+}
+
+/** Retain operationId and the exact request when reconciling an uncertain outcome. */
+export async function updateOrganizationIntegrationPolicy(
+  client: PolicyClient,
+  organizationId: string,
+  request: UpdateOrganizationIntegrationPolicyRequest,
+): Promise<OrganizationIntegrationPolicy> {
+  return client.requestJson(
+    "PUT",
+    `/v1/organizations/${encodeURIComponent(organizationId)}/integration-policy`,
+    request,
+  );
+}

package/src/organization-private-session-settings.ts

@@ -0,0 +1,33 @@
+import type { OpenGeniClient } from "./client";
+import type {
+  OrganizationPrivateSessionSettings,
+  UpdateOrganizationPrivateSessionSettingsRequest,
+} from "./types";
+
+type OrganizationPrivateSessionSettingsClient = Pick<OpenGeniClient, "requestJson">;
+
+function settingsPath(organizationId: string): string {
+  return `/v1/organizations/${organizationId}/private-session-settings`;
+}
+
+export async function getOrganizationPrivateSessionSettings(
+  client: OrganizationPrivateSessionSettingsClient,
+  organizationId: string,
+): Promise<OrganizationPrivateSessionSettings> {
+  return await client.requestJson<OrganizationPrivateSessionSettings>(
+    "GET",
+    settingsPath(organizationId),
+  );
+}
+
+export async function updateOrganizationPrivateSessionSettings(
+  client: OrganizationPrivateSessionSettingsClient,
+  organizationId: string,
+  request: UpdateOrganizationPrivateSessionSettingsRequest,
+): Promise<OrganizationPrivateSessionSettings> {
+  return await client.requestJson<OrganizationPrivateSessionSettings>(
+    "PATCH",
+    settingsPath(organizationId),
+    request,
+  );
+}

package/src/organization-user-setup.ts

@@ -0,0 +1,31 @@
+import type { OpenGeniClient } from "./client";
+import type {
+  OrganizationUserSetupDelivery,
+  OrganizationUserSetupPreview,
+  PreviewOrganizationUserSetupRequest,
+  RetryOrganizationUserSetupDeliveryRequest,
+} from "./types";
+
+type OrganizationUserSetupClient = Pick<OpenGeniClient, "requestJson">;
+
+/** Safe signed-out projection of the exact organization role and shared access in a setup link. */
+export function previewOrganizationUserSetup(
+  client: OrganizationUserSetupClient,
+  request: PreviewOrganizationUserSetupRequest,
+): Promise<OrganizationUserSetupPreview> {
+  return client.requestJson("POST", "/v1/auth/organization-setup/preview", request);
+}
+
+/** Retry a failed or explicitly outcome-unknown delivery with its stable provider key. */
+export function retryOrganizationUserSetupDelivery(
+  client: OrganizationUserSetupClient,
+  organizationId: string,
+  invitationId: string,
+  request: RetryOrganizationUserSetupDeliveryRequest,
+): Promise<OrganizationUserSetupDelivery> {
+  return client.requestJson(
+    "POST",
+    `/v1/organizations/${organizationId}/invitations/${invitationId}/delivery/retry`,
+    request,
+  );
+}

package/src/pr-review-client.ts

@@ -0,0 +1,92 @@
+import type { OpenGeniClient as OpenGeniCoreClient } from "./client";
+import type {
+  CreatePrReviewAppRegistrationRequest,
+  CreatePrReviewRepositoryBindingRequest,
+  PrReviewAppRegistration,
+  PrReviewRepositoryBinding,
+  ListPrReviewConfigurationResponse,
+  PrReviewManagedGitHubSetup,
+  UpdatePrReviewAppRegistrationRequest,
+  UpdatePrReviewRepositoryBindingRequest,
+} from "./types";
+
+export type OpenGeniPrReviewTransport = Pick<OpenGeniCoreClient, "requestJson" | "requestVoid">;
+
+/** Optional OpenGeni Review Bot API surface, isolated from the eager core client graph. */
+export class OpenGeniPrReviewClient {
+  constructor(private readonly client: OpenGeniPrReviewTransport) {}
+
+  async listConfiguration(workspaceId: string): Promise<ListPrReviewConfigurationResponse> {
+    return await this.client.requestJson<ListPrReviewConfigurationResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/pr-review/registrations`,
+    );
+  }
+
+  async getManagedGitHubSetup(workspaceId: string): Promise<PrReviewManagedGitHubSetup> {
+    return await this.client.requestJson<PrReviewManagedGitHubSetup>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/pr-review/github`,
+    );
+  }
+
+  async createAppRegistration(
+    workspaceId: string,
+    request: CreatePrReviewAppRegistrationRequest,
+  ): Promise<PrReviewAppRegistration> {
+    return await this.client.requestJson<PrReviewAppRegistration>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/pr-review/registrations`,
+      request,
+    );
+  }
+
+  async updateAppRegistration(
+    workspaceId: string,
+    registrationId: string,
+    request: UpdatePrReviewAppRegistrationRequest,
+  ): Promise<PrReviewAppRegistration> {
+    return await this.client.requestJson<PrReviewAppRegistration>(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/pr-review/registrations/${encodeURIComponent(registrationId)}`,
+      request,
+    );
+  }
+
+  async deleteAppRegistration(workspaceId: string, registrationId: string): Promise<void> {
+    await this.client.requestVoid(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/pr-review/registrations/${encodeURIComponent(registrationId)}`,
+    );
+  }
+
+  async createRepositoryBinding(
+    workspaceId: string,
+    request: CreatePrReviewRepositoryBindingRequest,
+  ): Promise<PrReviewRepositoryBinding> {
+    return await this.client.requestJson<PrReviewRepositoryBinding>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/pr-review/repositories`,
+      request,
+    );
+  }
+
+  async updateRepositoryBinding(
+    workspaceId: string,
+    bindingId: string,
+    request: UpdatePrReviewRepositoryBindingRequest,
+  ): Promise<PrReviewRepositoryBinding> {
+    return await this.client.requestJson<PrReviewRepositoryBinding>(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/pr-review/repositories/${encodeURIComponent(bindingId)}`,
+      request,
+    );
+  }
+
+  async deleteRepositoryBinding(workspaceId: string, bindingId: string): Promise<void> {
+    await this.client.requestVoid(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/pr-review/repositories/${encodeURIComponent(bindingId)}`,
+    );
+  }
+}

package/src/pr-review.ts

@@ -0,0 +1,17 @@
+/** Optional OpenGeni Review Bot API client; import this entry only where the capability is used. */
+export { OpenGeniPrReviewClient } from "./pr-review-client";
+export type { OpenGeniPrReviewTransport } from "./pr-review-client";
+export type {
+  CreatePrReviewAppRegistrationRequest,
+  CreatePrReviewRepositoryBindingRequest,
+  PrReviewAppRegistration,
+  PrReviewCredentialKind,
+  PrReviewProvider,
+  PrReviewManagedGitHubInstallation,
+  PrReviewManagedGitHubSetup,
+  PrReviewRepositoryBinding,
+  PrReviewWebhookAuthKind,
+  ListPrReviewConfigurationResponse,
+  UpdatePrReviewAppRegistrationRequest,
+  UpdatePrReviewRepositoryBindingRequest,
+} from "./types";

package/src/preference-registry.ts

@@ -10,6 +10,8 @@ export type PreferenceRegistryProvenanceSource =
   | "human"
   | "onboarding"
   | "knowledge_proposal"
+  | "agent"
+  | "portable_skill"
   | "imported_document"
   | "slack"
   | "meeting_transcript"
@@ -101,6 +103,8 @@ export type PreferenceRegistryEvent = {
   createdAt: string;
 };
 
+export type PreferenceRegistryActivationAuthority = "human_confirmed" | "automatic";
+
 export type PreferenceRegistryDescriptor = {
   id: string;
   stableKey: string;
@@ -112,6 +116,13 @@ export type PreferenceRegistryDescriptor = {
   contentHash: string;
   precedence: PreferenceRegistryPrecedence;
   provenance: PreferenceRegistryDescriptorProvenance;
+  /**
+   * How the active revision became active. `provenance.trust` stays the frozen
+   * creation-time fact; this is the separate activation question. Null when the
+   * revision became active outside governed learning, or when the descriptor
+   * predates this field.
+   */
+  activationAuthority: PreferenceRegistryActivationAuthority | null;
   expiresAt: string | null;
   retrievalHandle: string;
 };