@opengeni/contracts 0.44.1 → 1.0.0

package/src/organization-recovery.ts

@@ -0,0 +1,186 @@
+import { z } from "zod";
+
+const Uuid = z.string().uuid();
+const Timestamp = z.string().datetime({ offset: true });
+
+export const OrganizationRecoveryPolicyState = z.enum([
+  "pending_acceptance",
+  "active",
+  "degraded",
+  "superseded",
+  "disabled",
+]);
+export type OrganizationRecoveryPolicyState = z.infer<typeof OrganizationRecoveryPolicyState>;
+
+export const OrganizationRecoveryOperationState = z.enum([
+  "collecting",
+  "cooling",
+  "executed",
+  "cancelled",
+  "expired",
+  "superseded",
+]);
+export type OrganizationRecoveryOperationState = z.infer<typeof OrganizationRecoveryOperationState>;
+
+export const OrganizationRecoveryUnavailableReason = z.enum([
+  "no_policy",
+  "pending_acceptance",
+  "degraded",
+  "disabled",
+  "identity_unavailable",
+]);
+export type OrganizationRecoveryUnavailableReason = z.infer<
+  typeof OrganizationRecoveryUnavailableReason
+>;
+
+export const OrganizationRecoveryMemberSummary = z
+  .object({
+    membershipId: Uuid,
+    name: z.string().trim().min(1).max(1024).nullable(),
+    email: z.string().email().max(320).nullable(),
+  })
+  .strict();
+export type OrganizationRecoveryMemberSummary = z.infer<typeof OrganizationRecoveryMemberSummary>;
+
+export const OrganizationRecoveryCustodian = OrganizationRecoveryMemberSummary.extend({
+  ordinal: z.number().int().min(1).max(3),
+  enrollmentState: z.enum(["pending_acceptance", "accepted", "ineligible"]),
+  acceptedAt: Timestamp.nullable(),
+}).strict();
+export type OrganizationRecoveryCustodian = z.infer<typeof OrganizationRecoveryCustodian>;
+
+export const OrganizationRecoveryPolicy = z
+  .object({
+    id: Uuid,
+    organizationId: Uuid,
+    revision: z.number().int().positive(),
+    state: OrganizationRecoveryPolicyState,
+    custodians: z.array(OrganizationRecoveryCustodian).length(3),
+    createdAt: Timestamp,
+    updatedAt: Timestamp,
+  })
+  .strict();
+export type OrganizationRecoveryPolicy = z.infer<typeof OrganizationRecoveryPolicy>;
+
+export const OrganizationRecoveryApproval = OrganizationRecoveryMemberSummary.extend({
+  approvedAt: Timestamp,
+}).strict();
+export type OrganizationRecoveryApproval = z.infer<typeof OrganizationRecoveryApproval>;
+
+export const OrganizationRecoveryOperation = z
+  .object({
+    id: Uuid,
+    organizationId: Uuid,
+    policyId: Uuid,
+    policyRevision: z.number().int().positive(),
+    revision: z.number().int().positive(),
+    state: OrganizationRecoveryOperationState,
+    target: OrganizationRecoveryMemberSummary,
+    approvals: z.array(OrganizationRecoveryApproval).max(3),
+    approvalCount: z.number().int().min(0).max(3),
+    quorumAt: Timestamp.nullable(),
+    executableAt: Timestamp.nullable(),
+    expiresAt: Timestamp,
+    executedAt: Timestamp.nullable(),
+    cancelledAt: Timestamp.nullable(),
+    notificationJournaled: z.boolean(),
+    createdAt: Timestamp,
+    updatedAt: Timestamp,
+  })
+  .strict();
+export type OrganizationRecoveryOperation = z.infer<typeof OrganizationRecoveryOperation>;
+
+export const OrganizationRecoveryCapabilities = z
+  .object({
+    configure: z.boolean(),
+    accept: z.boolean(),
+    disable: z.boolean(),
+    start: z.boolean(),
+    approve: z.boolean(),
+    cancel: z.boolean(),
+    execute: z.boolean(),
+  })
+  .strict();
+export type OrganizationRecoveryCapabilities = z.infer<typeof OrganizationRecoveryCapabilities>;
+
+export const OrganizationRecoveryOverview = z
+  .object({
+    organizationId: Uuid,
+    availability: z.enum(["available", "recovery_unavailable"]),
+    unavailableReason: OrganizationRecoveryUnavailableReason.nullable(),
+    recentReauthenticationAt: Timestamp.nullable(),
+    eligibleMembers: z.array(OrganizationRecoveryMemberSummary).max(1000),
+    policy: OrganizationRecoveryPolicy.nullable(),
+    operation: OrganizationRecoveryOperation.nullable(),
+    capabilities: OrganizationRecoveryCapabilities,
+  })
+  .strict();
+export type OrganizationRecoveryOverview = z.infer<typeof OrganizationRecoveryOverview>;
+
+const ExpectedPolicyRevision = z.number().int().nonnegative();
+const ExpectedOperationRevision = z.number().int().positive();
+const CommandOperationId = Uuid;
+
+export const ConfigureOrganizationRecoveryPolicyRequest = z
+  .object({
+    custodianMembershipIds: z.tuple([Uuid, Uuid, Uuid]).superRefine((ids, context) => {
+      if (new Set(ids).size !== 3) {
+        context.addIssue({
+          code: "custom",
+          message: "recovery custodians must be three distinct memberships",
+        });
+      }
+    }),
+    expectedPolicyRevision: ExpectedPolicyRevision,
+    operationId: CommandOperationId,
+  })
+  .strict();
+export type ConfigureOrganizationRecoveryPolicyRequest = z.infer<
+  typeof ConfigureOrganizationRecoveryPolicyRequest
+>;
+
+export const AcceptOrganizationRecoveryCustodyRequest = z
+  .object({
+    expectedPolicyRevision: ExpectedPolicyRevision,
+    operationId: CommandOperationId,
+  })
+  .strict();
+export type AcceptOrganizationRecoveryCustodyRequest = z.infer<
+  typeof AcceptOrganizationRecoveryCustodyRequest
+>;
+
+export const DisableOrganizationRecoveryPolicyRequest = AcceptOrganizationRecoveryCustodyRequest;
+export type DisableOrganizationRecoveryPolicyRequest = z.infer<
+  typeof DisableOrganizationRecoveryPolicyRequest
+>;
+
+export const StartOrganizationRecoveryOperationRequest = z
+  .object({
+    targetMembershipId: Uuid,
+    expectedPolicyRevision: z.number().int().positive(),
+    operationId: CommandOperationId,
+  })
+  .strict();
+export type StartOrganizationRecoveryOperationRequest = z.infer<
+  typeof StartOrganizationRecoveryOperationRequest
+>;
+
+export const OrganizationRecoveryOperationCommandRequest = z
+  .object({
+    expectedOperationRevision: ExpectedOperationRevision,
+    operationId: CommandOperationId,
+  })
+  .strict();
+export type OrganizationRecoveryOperationCommandRequest = z.infer<
+  typeof OrganizationRecoveryOperationCommandRequest
+>;
+
+export const OrganizationRecoveryMutationResponse = z
+  .object({
+    replay: z.boolean(),
+    overview: OrganizationRecoveryOverview,
+  })
+  .strict();
+export type OrganizationRecoveryMutationResponse = z.infer<
+  typeof OrganizationRecoveryMutationResponse
+>;

package/src/organization-usage.ts

@@ -0,0 +1,79 @@
+import { z } from "zod";
+
+export const OrganizationUsagePeriod = z.enum(["today", "week", "month", "ytd"]);
+export type OrganizationUsagePeriod = z.infer<typeof OrganizationUsagePeriod>;
+export const OrganizationUsageQuery = z.object({
+  period: OrganizationUsagePeriod.default("month"),
+});
+export const OrganizationUsageWorkspacePageQuery = OrganizationUsageQuery.extend({
+  until: z.string().datetime(),
+  afterWorkspaceId: z.string().uuid().optional(),
+});
+// PostgreSQL SUM(bigint) must never pass through a JavaScript number.
+export const OrganizationUsageTotal = z.object({
+  eventType: z.string(),
+  unit: z.string(),
+  quantity: z.string().regex(/^-?\d+$/),
+  eventCount: z.string().regex(/^\d+$/),
+});
+/** One member's Personal workspace, as usage only. */
+export const OrganizationUsagePersonalWorkspace = z.object({
+  membershipId: z.string().uuid(),
+  totals: z.array(OrganizationUsageTotal),
+});
+export type OrganizationUsagePersonalWorkspace = z.infer<typeof OrganizationUsagePersonalWorkspace>;
+export const OrganizationUsageSummary = z.object({
+  accountId: z.string().uuid(),
+  period: OrganizationUsagePeriod,
+  since: z.string().datetime(),
+  until: z.string().datetime(),
+  granularity: z.enum(["hour", "day"]),
+  totals: z.array(OrganizationUsageTotal),
+  buckets: z.array(z.object({ bucket: z.string(), totals: z.array(OrganizationUsageTotal) })),
+  workspaces: z
+    .array(
+      z.object({
+        workspaceId: z.string().uuid(),
+        name: z.string().nullable(),
+        totals: z.array(OrganizationUsageTotal),
+      }),
+    )
+    .max(50),
+  nextWorkspaceCursor: z.string().uuid().nullable(),
+  /**
+   * Usage in each member's Personal workspace, keyed by the owner's
+   * organization membership: amounts only, never the workspace's id, name or
+   * content. Only Personal workspaces with usage in the period, the 50 that
+   * spent the most. Absent before migration 0543, hence the defaults.
+   */
+  personalWorkspaces: z.array(OrganizationUsagePersonalWorkspace).max(50).default([]),
+  /** How many Personal workspaces had usage in the period, listed or not. */
+  personalWorkspaceCount: z.number().int().nonnegative().default(0),
+  /** Other people's Only-me chats in shared workspaces: member amounts only. */
+  privateChats: z
+    .array(
+      z.object({
+        workspaceId: z.string().uuid(),
+        membershipId: z.string().uuid().nullable(),
+        name: z.string().nullable(),
+        totals: z.array(OrganizationUsageTotal),
+      }),
+    )
+    .default([]),
+  privateChatsTruncated: z.boolean().default(false),
+});
+export type OrganizationUsageSummary = z.infer<typeof OrganizationUsageSummary>;
+
+/**
+ * A page deliberately excludes totals, charts and Personal rows: those are not
+ * recomputed. Pages continue the shared workspaces only.
+ */
+export const OrganizationUsageWorkspacePage = OrganizationUsageSummary.omit({
+  totals: true,
+  buckets: true,
+  personalWorkspaces: true,
+  personalWorkspaceCount: true,
+  privateChats: true,
+  privateChatsTruncated: true,
+});
+export type OrganizationUsageWorkspacePage = z.infer<typeof OrganizationUsageWorkspacePage>;

package/src/permissions.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+
+/** Canonical public permission vocabulary shared by operational and control-plane contracts. */
+export const Permission = z.enum([
+  "account:read",
+  "account:admin",
+  "members:manage",
+  "workspace:create",
+  "billing:read",
+  "billing:manage",
+  "workspace:read",
+  "workspace:admin",
+  "sessions:create",
+  "sessions:read",
+  "sessions:control",
+  "stream:view",
+  "stream:control",
+  "stream:acknowledge",
+  "files:upload",
+  "files:read",
+  "files:write",
+  "terminal:attach",
+  "documents:manage",
+  "documents:search",
+  "scheduled_tasks:manage",
+  "scheduled_tasks:run",
+  "github:manage",
+  "github:use",
+  "api_keys:manage",
+  /** Literal organization-key authority to configure workspace usage allowances. */
+  "usage_allowances:manage",
+  "connections:read",
+  "connections:write",
+  "capabilities:manage",
+  /** @deprecated alias of variable-sets:manage */
+  "environments:manage",
+  /** @deprecated alias of variable-sets:use */
+  "environments:use",
+  "variable-sets:list",
+  "variable-sets:read",
+  "variable-sets:write",
+  "variable-sets:manage",
+  "variable-sets:attach",
+  "variable-sets:use",
+  "secrets:list",
+  "secrets:read",
+  "secrets:write",
+  "mcp_servers:attach",
+  "codemode:call",
+  "goals:manage",
+  "enrollments:read",
+  "enrollments:manage",
+  "rigs:use",
+  "rigs:manage",
+  "artifacts:read",
+  "artifacts:publish",
+]);
+export type Permission = z.infer<typeof Permission>;

package/src/personal-github.ts

@@ -0,0 +1,267 @@
+import { z } from "zod";
+
+import { ConnectionMetadata } from "./index";
+
+export const PERSONAL_GITHUB_PROVIDER_DOMAIN = "github.com" as const;
+export const PERSONAL_GITHUB_PROVIDER_FAMILY = "github" as const;
+export const PERSONAL_GITHUB_CREDENTIAL_ROLE = "opengeni_github_personal" as const;
+export const PERSONAL_GITHUB_CONNECTION_SURFACE_ID = "github:personal" as const;
+export const PERSONAL_GITHUB_REQUESTED_SCOPES = ["repo"] as const;
+export const PERSONAL_GITHUB_AUTHORIZATION_URL =
+  "https://github.com/login/oauth/authorize" as const;
+export const PERSONAL_GITHUB_TOKEN_URL = "https://github.com/login/oauth/access_token" as const;
+export const PERSONAL_GITHUB_USER_URL = "https://api.github.com/user" as const;
+export const PERSONAL_GITHUB_API_ORIGIN = "https://api.github.com" as const;
+export const PERSONAL_GITHUB_REPOSITORY_CATALOG_MAX = 100 as const;
+
+export const PersonalGitHubRepositoryId = z.string().regex(/^[1-9]\d*$/u);
+export type PersonalGitHubRepositoryId = z.infer<typeof PersonalGitHubRepositoryId>;
+
+export const PersonalGitHubRepositoryAccess = z.enum(["read", "write"]);
+export type PersonalGitHubRepositoryAccess = z.infer<typeof PersonalGitHubRepositoryAccess>;
+
+export const PersonalGitHubRepositoryPermissions = z
+  .object({
+    pull: z.boolean(),
+    push: z.boolean(),
+    admin: z.boolean(),
+    maintain: z.boolean(),
+    triage: z.boolean(),
+  })
+  .strict();
+export type PersonalGitHubRepositoryPermissions = z.infer<
+  typeof PersonalGitHubRepositoryPermissions
+>;
+
+export const PersonalGitHubRepositoryVisibility = z.enum(["public", "private", "internal"]);
+export type PersonalGitHubRepositoryVisibility = z.infer<typeof PersonalGitHubRepositoryVisibility>;
+
+const PersonalGitHubRepositoryFullName = z
+  .string()
+  .min(3)
+  .max(140)
+  .regex(/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})\/[A-Za-z0-9_.-]{1,100}$/u);
+
+export function canonicalPersonalGitHubRepositoryUrl(fullName: string): string {
+  return `https://github.com/${fullName}`;
+}
+
+/** A bounded, credential-free projection verified directly against GitHub. */
+export const PersonalGitHubRepository = z
+  .object({
+    repositoryId: PersonalGitHubRepositoryId,
+    fullName: PersonalGitHubRepositoryFullName,
+    canonicalUrl: z.string().url().max(512),
+    defaultBranch: z.string().min(1).max(255),
+    visibility: PersonalGitHubRepositoryVisibility,
+    private: z.boolean(),
+    archived: z.boolean(),
+    disabled: z.boolean(),
+    permissions: PersonalGitHubRepositoryPermissions,
+  })
+  .strict()
+  .superRefine((repository, context) => {
+    if (repository.canonicalUrl !== canonicalPersonalGitHubRepositoryUrl(repository.fullName)) {
+      context.addIssue({
+        code: "custom",
+        path: ["canonicalUrl"],
+        message: "canonicalUrl must be derived from fullName",
+      });
+    }
+    if (repository.private !== (repository.visibility === "private")) {
+      context.addIssue({
+        code: "custom",
+        path: ["private"],
+        message: "private must agree with visibility",
+      });
+    }
+  });
+export type PersonalGitHubRepository = z.infer<typeof PersonalGitHubRepository>;
+
+export const PersonalGitHubSelectedRepository = PersonalGitHubRepository.safeExtend({
+  selectedAccess: PersonalGitHubRepositoryAccess,
+  selectionGeneration: z.number().int().positive(),
+  selectedAt: z.string().datetime({ offset: true }),
+  lastVerifiedAt: z.string().datetime({ offset: true }),
+}).strict();
+export type PersonalGitHubSelectedRepository = z.infer<typeof PersonalGitHubSelectedRepository>;
+
+export const PersonalGitHubRepositorySelectionState = z
+  .object({
+    connectionAuthorityGeneration: z.number().int().positive(),
+    credentialBindingId: z.string().uuid(),
+    providerPrincipalId: PersonalGitHubRepositoryId,
+    selectionGeneration: z.number().int().nonnegative(),
+    repositories: z
+      .array(PersonalGitHubSelectedRepository)
+      .max(PERSONAL_GITHUB_REPOSITORY_CATALOG_MAX),
+  })
+  .strict();
+export type PersonalGitHubRepositorySelectionState = z.infer<
+  typeof PersonalGitHubRepositorySelectionState
+>;
+
+export const ListPersonalGitHubRepositoriesQuery = z
+  .object({
+    cursor: z.coerce.number().int().positive().max(10_000).default(1),
+    limit: z.coerce.number().int().min(1).max(PERSONAL_GITHUB_REPOSITORY_CATALOG_MAX).default(50),
+  })
+  .strict();
+export type ListPersonalGitHubRepositoriesQuery = z.infer<
+  typeof ListPersonalGitHubRepositoriesQuery
+>;
+
+export const PersonalGitHubRepositoryCatalogItem = PersonalGitHubRepository.safeExtend({
+  selectedAccess: PersonalGitHubRepositoryAccess.nullable(),
+}).strict();
+export type PersonalGitHubRepositoryCatalogItem = z.infer<
+  typeof PersonalGitHubRepositoryCatalogItem
+>;
+
+export const ListPersonalGitHubRepositoriesResponse = z
+  .object({
+    repositories: z
+      .array(PersonalGitHubRepositoryCatalogItem)
+      .max(PERSONAL_GITHUB_REPOSITORY_CATALOG_MAX),
+    nextCursor: z.number().int().positive().nullable(),
+    selection: PersonalGitHubRepositorySelectionState,
+  })
+  .strict();
+export type ListPersonalGitHubRepositoriesResponse = z.infer<
+  typeof ListPersonalGitHubRepositoriesResponse
+>;
+
+export const PersonalGitHubRepositorySelectionInput = z
+  .object({
+    repositoryId: PersonalGitHubRepositoryId,
+    fullName: PersonalGitHubRepositoryFullName,
+    access: PersonalGitHubRepositoryAccess,
+  })
+  .strict();
+export type PersonalGitHubRepositorySelectionInput = z.infer<
+  typeof PersonalGitHubRepositorySelectionInput
+>;
+
+export const ReplacePersonalGitHubRepositorySelectionsRequest = z
+  .object({
+    expectedConnectionAuthorityGeneration: z.number().int().positive(),
+    expectedSelectionGeneration: z.number().int().nonnegative(),
+    idempotencyKey: z.string().trim().min(1).max(200),
+    repositories: z
+      .array(PersonalGitHubRepositorySelectionInput)
+      .max(PERSONAL_GITHUB_REPOSITORY_CATALOG_MAX),
+  })
+  .strict()
+  .superRefine((request, context) => {
+    const repositoryIds = new Set<string>();
+    const fullNames = new Set<string>();
+    request.repositories.forEach((repository, index) => {
+      const normalizedFullName = repository.fullName.toLowerCase();
+      if (repositoryIds.has(repository.repositoryId)) {
+        context.addIssue({
+          code: "custom",
+          path: ["repositories", index, "repositoryId"],
+          message: "repositoryId must be unique",
+        });
+      }
+      if (fullNames.has(normalizedFullName)) {
+        context.addIssue({
+          code: "custom",
+          path: ["repositories", index, "fullName"],
+          message: "fullName must be unique",
+        });
+      }
+      repositoryIds.add(repository.repositoryId);
+      fullNames.add(normalizedFullName);
+    });
+  });
+export type ReplacePersonalGitHubRepositorySelectionsRequest = z.infer<
+  typeof ReplacePersonalGitHubRepositorySelectionsRequest
+>;
+
+export const VerifyPersonalGitHubRepositorySelectionsRequest = z
+  .object({
+    expectedConnectionAuthorityGeneration: z.number().int().positive(),
+    expectedSelectionGeneration: z.number().int().nonnegative(),
+    idempotencyKey: z.string().trim().min(1).max(200),
+  })
+  .strict();
+export type VerifyPersonalGitHubRepositorySelectionsRequest = z.infer<
+  typeof VerifyPersonalGitHubRepositorySelectionsRequest
+>;
+
+/**
+ * Owner-visible, credential-free metadata for one dedicated personal GitHub
+ * OAuth connection. Repository selections are a separate authority and never
+ * live in this credential record.
+ */
+export const PersonalGitHubConnectionMetadata = z
+  .object({
+    credentialRole: z.literal(PERSONAL_GITHUB_CREDENTIAL_ROLE),
+    providerFamily: z.literal(PERSONAL_GITHUB_PROVIDER_FAMILY),
+    providerPrincipalId: z.string().regex(/^\d+$/u),
+    githubUserId: z.string().regex(/^\d+$/u),
+    githubLogin: z.string().min(1).max(100),
+    oauthEnvironment: z.string().min(1).max(128),
+    oauthClientMarker: z.string().regex(/^[a-f0-9]{32}$/u),
+    credentialBindingId: z.string().uuid(),
+    connectedAt: z.string().datetime({ offset: true }),
+    lastVerifiedAt: z.string().datetime({ offset: true }),
+    disconnectedAt: z.string().datetime({ offset: true }).nullable().optional(),
+    refreshTokenExpiresAt: z.string().datetime({ offset: true }).nullable().optional(),
+  })
+  .passthrough();
+export type PersonalGitHubConnectionMetadata = z.infer<typeof PersonalGitHubConnectionMetadata>;
+
+export const PersonalGitHubOAuthStartRequest = z
+  .object({
+    /** Existing exact connection generation to re-authorize in place. */
+    connectionId: z.string().uuid().optional(),
+    /** Same-workspace UI path restored after the callback. */
+    returnPath: z.string().min(1).max(2048).optional(),
+  })
+  .strict();
+export type PersonalGitHubOAuthStartRequest = z.infer<typeof PersonalGitHubOAuthStartRequest>;
+
+export const PersonalGitHubOAuthStartResponse = z
+  .object({
+    authorizationUrl: z.string().url(),
+    expiresAt: z.string().datetime({ offset: true }),
+  })
+  .strict();
+export type PersonalGitHubOAuthStartResponse = z.infer<typeof PersonalGitHubOAuthStartResponse>;
+
+export const PersonalGitHubConnectionStatusResponse = z
+  .object({
+    enabled: z.boolean(),
+    connection: ConnectionMetadata.nullable(),
+    reviewUrl: z.string().url().nullable(),
+  })
+  .strict();
+export type PersonalGitHubConnectionStatusResponse = z.infer<
+  typeof PersonalGitHubConnectionStatusResponse
+>;
+
+export const PersonalGitHubDisconnectRequest = z
+  .object({
+    expectedVersion: z.number().int().positive(),
+    idempotencyKey: z.string().trim().min(1).max(200),
+  })
+  .strict();
+export type PersonalGitHubDisconnectRequest = z.infer<typeof PersonalGitHubDisconnectRequest>;
+
+export function isPersonalGitHubConnection(
+  connection: Pick<z.infer<typeof ConnectionMetadata>, "providerDomain" | "kind" | "metadata">,
+): boolean {
+  return (
+    connection.providerDomain.toLowerCase() === PERSONAL_GITHUB_PROVIDER_DOMAIN &&
+    connection.kind === "oauth2" &&
+    PersonalGitHubConnectionMetadata.safeParse(connection.metadata).success
+  );
+}
+
+export function hasReservedPersonalGitHubMetadata(
+  metadata: Record<string, unknown> | undefined,
+): boolean {
+  return metadata?.credentialRole === PERSONAL_GITHUB_CREDENTIAL_ROLE;
+}

package/src/plugin-discovery.ts

@@ -0,0 +1,33 @@
+/** Public discovery metadata; listing does not imply runtime compatibility. */
+export { pluginMcpUnavailableReason } from "./mcp-endpoint";
+
+export type PluginDiscoveryItem = {
+  id: string;
+  name: string;
+  displayName: string;
+  description: string;
+  longDescription: string;
+  provider: string;
+  category: string | null;
+  logoUrl: string | null;
+  darkLogoUrl: string | null;
+  sourceUrl: string | null;
+  author: { name?: string } | null;
+  version: string | null;
+  skills?: { name: string; sourceUrl: string }[] | null;
+  mcpServers?:
+    | {
+        name: string;
+        transport: string;
+        requiresConfiguration?: boolean;
+        endpoint: string | null;
+      }[]
+    | null;
+  components: string[] | null;
+  installation: string;
+};
+export type PluginDiscoveryPage = {
+  items: PluginDiscoveryItem[];
+  total: number;
+  nextOffset: number | null;
+};

package/src/preference-registry.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 
 export const PREFERENCE_REGISTRY_CONTENT_MAX_CHARS = 262_144;
-export const PREFERENCE_REGISTRY_DESCRIPTOR_DESCRIPTION_MAX_CHARS = 240;
+export const PREFERENCE_REGISTRY_DESCRIPTOR_DESCRIPTION_MAX_CHARS = 1024;
 export const PREFERENCE_REGISTRY_DESCRIPTOR_MAX_COUNT = 64;
 export const PREFERENCE_REGISTRY_DESCRIPTOR_MAX_UTF8_BYTES = 16_384;
 export const PREFERENCE_REGISTRY_REASON_MAX_CHARS = 4_096;
@@ -30,6 +30,8 @@ export const PreferenceRegistryProvenanceSource = z.enum([
   "slack",
   "meeting_transcript",
   "call_transcript",
+  "agent",
+  "portable_skill",
 ]);
 export type PreferenceRegistryProvenanceSource = z.infer<typeof PreferenceRegistryProvenanceSource>;
 
@@ -174,6 +176,11 @@ export const PreferenceRegistryEvent = z.object({
 });
 export type PreferenceRegistryEvent = z.infer<typeof PreferenceRegistryEvent>;
 
+export const PreferenceRegistryActivationAuthority = z.enum(["human_confirmed", "automatic"]);
+export type PreferenceRegistryActivationAuthority = z.infer<
+  typeof PreferenceRegistryActivationAuthority
+>;
+
 export const PreferenceRegistryDescriptor = z.object({
   id: z.string().uuid(),
   stableKey: PreferenceRegistryStableKey,
@@ -185,6 +192,18 @@ export const PreferenceRegistryDescriptor = z.object({
   contentHash: hash,
   precedence: PreferenceRegistryPrecedence,
   provenance: PreferenceRegistryDescriptorProvenance,
+  // How the active revision became active, derived from the governed-learning
+  // activation receipt rather than stored on the revision. `provenance.trust`
+  // stays the frozen creation-time fact - a revision proposed by an agent is
+  // `untrusted_proposal` forever, which is correct and immutable - while this
+  // says whether a human explicitly confirmed the activation or policy
+  // activated it automatically. Null when the revision became active outside
+  // governed learning, so no receipt describes it.
+  // Defaulted, not merely nullable: snapshots written before this field
+  // existed are immutable and their stored JSON simply has no answer. Parsing
+  // those as null is the truthful reading, and it keeps their pinned
+  // descriptor hash valid because the stored text is untouched.
+  activationAuthority: PreferenceRegistryActivationAuthority.nullable().default(null),
   expiresAt: z.string().datetime().nullable(),
   retrievalHandle: z.string().min(1).max(512),
 });