@opengeni/contracts 0.50.0 → 2.2.0-canary.0

package/src/interaction.ts

@@ -364,9 +364,25 @@ export const AttachedBrowserDevice = z
   });
 export type AttachedBrowserDevice = z.infer<typeof AttachedBrowserDevice>;
 
+/** One enrolled machine agent currently reporting its browser-bridge inventory.
+ * A bridge with zero devices is operational but has no Chrome profile connected
+ * through the OpenGeni extension yet. */
+export const AttachedBrowserBridge = z
+  .object({
+    enrollmentId: z.string().uuid(),
+    state: z.enum(["online", "offline"]),
+    bridgeGeneration: opaqueGeneration,
+    inventoryRevision: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+    connectedProfileCount: z.number().int().nonnegative().max(10_000),
+    lastSeenAt: z.string().datetime({ offset: true }),
+  })
+  .strict();
+export type AttachedBrowserBridge = z.infer<typeof AttachedBrowserBridge>;
+
 export const AttachedBrowserDeviceListResponse = z
   .object({
     revision: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+    bridges: z.array(AttachedBrowserBridge).max(10_000),
     devices: z.array(AttachedBrowserDevice).max(10_000),
   })
   .strict();
@@ -2162,6 +2178,41 @@ export const BrowserActionBatch = z
   });
 export type BrowserActionBatch = z.infer<typeof BrowserActionBatch>;
 
+/** Secret-safe projection of a connected-machine control failure carried in a
+ * standard API error envelope. The outer envelope owns HTTP status, retryability,
+ * and public request correlation; this preserves the exact failing control class
+ * and optional inner request id without exposing subjects, local paths, or tokens. */
+export const InteractionControlFailureCode = z.enum([
+  "unknown",
+  "unsupported",
+  "os",
+  "not_found",
+  "consent_required",
+  "timeout",
+  "draining",
+  "protocol",
+  "stream",
+  "agent_offline",
+  "fenced",
+  "payload_too_large",
+]);
+export type InteractionControlFailureCode = z.infer<typeof InteractionControlFailureCode>;
+
+export const InteractionControlFailureDetails = z
+  .object({
+    interactionLayer: z.literal("connected_machine"),
+    interactionSurface: z.enum(["browser", "computer"]),
+    controlFailureCode: InteractionControlFailureCode,
+    controlRequestId: z
+      .string()
+      .min(1)
+      .max(128)
+      .regex(/^[A-Za-z0-9._:-]+$/u)
+      .optional(),
+  })
+  .strict();
+export type InteractionControlFailureDetails = z.infer<typeof InteractionControlFailureDetails>;
+
 export const InteractionError = z
   .object({
     code: z.enum([
@@ -2502,11 +2553,14 @@ const DirectInteractionFrameStreamAttachment = z
   })
   .strict();
 
+/** Native tunnels offer `binary` + RFB + bearer (3). Docker and OpenSandbox
+ * hide those on the API interaction frame-proxy, so the viewer sees `binary` +
+ * the proxy grant (2). */
 const DirectComputerRfbAttachment = z
   .object({
     kind: z.literal("direct_rfb"),
     url: boundedUrl,
-    protocols: z.array(z.string().min(1).max(2_048)).length(3),
+    protocols: z.array(z.string().min(1).max(2_048)).min(2).max(3),
   })
   .strict();
 

package/src/knowledge.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 export const KNOWLEDGE_BROWSE_CURSOR_MAX_CHARS = 1_024;
 export const KNOWLEDGE_BROWSE_DEFAULT_LIMIT = 20;
 export const KNOWLEDGE_BROWSE_MAX_LIMIT = 50;
+export const KNOWLEDGE_BROWSE_MAX_RESPONSE_BYTES = 64 * 1_024;
 export const KNOWLEDGE_TITLE_MAX_BYTES = 1_024;
 export const KNOWLEDGE_BODY_MAX_BYTES = 16 * 1_024;
 export const KNOWLEDGE_SUMMARY_MAX_BYTES = 4 * 1_024;
@@ -13,6 +14,16 @@ export const KNOWLEDGE_METADATA_MAX_ITEMS = 64;
 export const KNOWLEDGE_METADATA_MAX_DEPTH = 4;
 export const KNOWLEDGE_SOURCE_STRING_MAX_BYTES = 2_048;
 export const KNOWLEDGE_SOURCE_URI_MAX_BYTES = 8_192;
+export const KNOWLEDGE_SEARCH_MAX_RESULTS = 50;
+export const KNOWLEDGE_SEARCH_MAX_RESPONSE_BYTES = 64 * 1_024;
+export const KNOWLEDGE_SEARCH_TOKEN_ESTIMATE_BYTES_PER_TOKEN = 4;
+export const KNOWLEDGE_SEARCH_MAX_FLOOR_OMISSIONS = 200;
+// Cosine similarity for unrelated embeddings clusters around 0.5 after the
+// distance conversion used by Documents. Keyword search already excludes
+// non-matches in SQL, but a small normalized floor removes incidental hits.
+export const KNOWLEDGE_SEARCH_MIN_VECTOR_SCORE = 0.52;
+export const KNOWLEDGE_SEARCH_MIN_KEYWORD_SCORE = 0.01;
+export const KNOWLEDGE_QUERY_MAX_BYTES = 4 * 1_024;
 
 const utf8Bytes = (value: string): number => new TextEncoder().encode(value).byteLength;
 const boundedUtf8 = (maxBytes: number) =>
@@ -102,6 +113,59 @@ export const KnowledgeSource = z.object({
 });
 export type KnowledgeSource = z.infer<typeof KnowledgeSource>;
 
+export const KnowledgeSearchRequest = z
+  .object({
+    query: boundedUtf8(KNOWLEDGE_QUERY_MAX_BYTES).pipe(z.string().min(1)),
+    baseIds: z.array(z.string().uuid()).max(50).optional(),
+    mode: z.enum(["hybrid", "vector", "keyword"]).optional(),
+    sourceKinds: z.array(KnowledgeSource.shape.kind).max(8).optional(),
+    aclTags: z
+      .array(boundedUtf8(KNOWLEDGE_TOPIC_MAX_BYTES).pipe(z.string().min(1)))
+      .max(64)
+      .optional(),
+    limit: z.number().int().positive().max(KNOWLEDGE_SEARCH_MAX_RESULTS).default(5),
+  })
+  .strict();
+export type KnowledgeSearchRequest = z.input<typeof KnowledgeSearchRequest>;
+
+export const KnowledgeBrowseRequest = z
+  .object({
+    parentId: KnowledgeRecordId.optional(),
+    topic: boundedUtf8(KNOWLEDGE_TOPIC_MAX_BYTES).pipe(z.string().min(1)).optional(),
+    sourceKinds: z.array(KnowledgeSource.shape.kind).max(8).optional(),
+    cursor: z.string().min(1).max(KNOWLEDGE_BROWSE_CURSOR_MAX_CHARS).optional(),
+    limit: z
+      .number()
+      .int()
+      .positive()
+      .max(KNOWLEDGE_BROWSE_MAX_LIMIT)
+      .default(KNOWLEDGE_BROWSE_DEFAULT_LIMIT),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    if (value.parentId && (value.topic || (value.sourceKinds?.length ?? 0) > 0)) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "document contents do not accept topic or source filters",
+      });
+    }
+  });
+export type KnowledgeBrowseRequest = z.input<typeof KnowledgeBrowseRequest>;
+
+export const KnowledgeProviderCitation = z.object({
+  provider: z.literal("google_drive"),
+  externalObjectId: boundedUtf8(KNOWLEDGE_SOURCE_STRING_MAX_BYTES),
+  providerRevision: boundedUtf8(KNOWLEDGE_SOURCE_STRING_MAX_BYTES).nullable(),
+  sourceVersion: boundedUtf8(KNOWLEDGE_SOURCE_STRING_MAX_BYTES),
+  driveId: boundedUtf8(KNOWLEDGE_SOURCE_STRING_MAX_BYTES).nullable(),
+  deepLink: boundedUtf8(KNOWLEDGE_SOURCE_URI_MAX_BYTES).pipe(z.string().min(1)).nullable(),
+  aclRevision: z.string().regex(/^[0-9a-f]{64}$/u),
+  authorizationObservedAt: z.string().datetime({ offset: true }),
+  authorizationExpiresAt: z.string().datetime({ offset: true }),
+  reauthorizedAt: z.string().datetime({ offset: true }),
+});
+export type KnowledgeProviderCitation = z.infer<typeof KnowledgeProviderCitation>;
+
 export const KnowledgeLinkTarget = z.discriminatedUnion("kind", [
   z.object({
     kind: z.literal("knowledge"),
@@ -144,6 +208,7 @@ export const KnowledgeRecord = z.object({
   provenance: z.object({
     source: KnowledgeSource,
     indexedAt: z.string(),
+    citation: KnowledgeProviderCitation.nullable().optional(),
   }),
   lifecycle: z.object({
     state: z.literal("active"),
@@ -171,9 +236,10 @@ export const KnowledgeRecord = z.object({
           "provenance.source.title",
           "provenance.source.author",
           "provenance.source.version",
+          "provenance.citation",
         ]),
       )
-      .max(10),
+      .max(11),
   }),
 });
 export type KnowledgeRecord = z.infer<typeof KnowledgeRecord>;
@@ -181,16 +247,59 @@ export type KnowledgeRecord = z.infer<typeof KnowledgeRecord>;
 export const KnowledgeSearchResult = z.object({
   record: KnowledgeRecord,
   retrieval: z.object({
-    score: z.number(),
+    /** Final bounded ordering score after the documented quality adjustment. */
+    score: z.number().min(0).max(1),
+    /** Semantic score before the quality adjustment. */
+    semanticScore: z.number().min(0).max(1),
     matchType: z.enum(["hybrid", "vector", "keyword"]),
-    vectorScore: z.number().nullable(),
-    keywordScore: z.number().nullable(),
+    vectorScore: z.number().min(0).max(1).nullable(),
+    keywordScore: z.number().min(0).max(1).nullable(),
+    relevanceSignals: z
+      .array(z.enum(["vector", "keyword"]))
+      .min(1)
+      .max(2),
+    freshness: z.enum(["current", "aging", "stale"]),
+    qualityAdjustment: z.number().min(0).max(1),
+    duplicateCount: z.number().int().nonnegative(),
   }),
 });
 export type KnowledgeSearchResult = z.infer<typeof KnowledgeSearchResult>;
 
 export const KnowledgeSearchResponse = z.object({
-  results: z.array(KnowledgeSearchResult),
+  results: z.array(KnowledgeSearchResult).max(KNOWLEDGE_SEARCH_MAX_RESULTS),
+  selection: z.object({
+    relevanceFloor: z.object({
+      policy: z.literal("any_signal"),
+      vectorScore: z.literal(KNOWLEDGE_SEARCH_MIN_VECTOR_SCORE),
+      keywordScore: z.literal(KNOWLEDGE_SEARCH_MIN_KEYWORD_SCORE),
+    }),
+    dedupe: z.object({
+      policy: z.literal("exact_textual_content"),
+    }),
+    candidates: z.object({
+      ranked: z.number().int().nonnegative().max(KNOWLEDGE_SEARCH_MAX_RESULTS),
+      rechecked: z.number().int().nonnegative().max(KNOWLEDGE_SEARCH_MAX_RESULTS),
+      omittedOnRecheck: z.number().int().nonnegative().max(KNOWLEDGE_SEARCH_MAX_RESULTS),
+    }),
+    omitted: z.object({
+      belowRelevanceFloor: z.number().int().nonnegative().max(KNOWLEDGE_SEARCH_MAX_FLOOR_OMISSIONS),
+      asDuplicate: z.number().int().nonnegative().max(KNOWLEDGE_SEARCH_MAX_RESULTS),
+      forLimit: z.number().int().nonnegative().max(KNOWLEDGE_SEARCH_MAX_RESULTS),
+      forResponseBudget: z.number().int().nonnegative().max(KNOWLEDGE_SEARCH_MAX_RESULTS),
+    }),
+    budget: z.object({
+      maxResults: z.literal(KNOWLEDGE_SEARCH_MAX_RESULTS),
+      maxResponseBytes: z.literal(KNOWLEDGE_SEARCH_MAX_RESPONSE_BYTES),
+      responseBytes: z.number().int().nonnegative().max(KNOWLEDGE_SEARCH_MAX_RESPONSE_BYTES),
+      tokenEstimateBytesPerToken: z.literal(KNOWLEDGE_SEARCH_TOKEN_ESTIMATE_BYTES_PER_TOKEN),
+      estimatedTokens: z.number().int().nonnegative(),
+      maxEstimatedTokens: z.literal(
+        Math.ceil(
+          KNOWLEDGE_SEARCH_MAX_RESPONSE_BYTES / KNOWLEDGE_SEARCH_TOKEN_ESTIMATE_BYTES_PER_TOKEN,
+        ),
+      ),
+    }),
+  }),
 });
 export type KnowledgeSearchResponse = z.infer<typeof KnowledgeSearchResponse>;
 
@@ -200,8 +309,26 @@ export const KnowledgeGetResponse = z.object({
 export type KnowledgeGetResponse = z.infer<typeof KnowledgeGetResponse>;
 
 export const KnowledgeBrowseResponse = z.object({
-  records: z.array(KnowledgeRecord),
+  records: z.array(KnowledgeRecord).max(KNOWLEDGE_BROWSE_MAX_LIMIT),
   nextCursor: z.string().min(1).max(KNOWLEDGE_BROWSE_CURSOR_MAX_CHARS).nullable(),
   hasMore: z.boolean(),
+  selection: z.object({
+    omitted: z.object({
+      forResponseBudget: z.number().int().nonnegative().max(KNOWLEDGE_BROWSE_MAX_LIMIT),
+    }),
+    compactedRecordCount: z.number().int().nonnegative().max(1),
+    budget: z.object({
+      maxResults: z.literal(KNOWLEDGE_BROWSE_MAX_LIMIT),
+      maxResponseBytes: z.literal(KNOWLEDGE_BROWSE_MAX_RESPONSE_BYTES),
+      responseBytes: z.number().int().nonnegative().max(KNOWLEDGE_BROWSE_MAX_RESPONSE_BYTES),
+      tokenEstimateBytesPerToken: z.literal(KNOWLEDGE_SEARCH_TOKEN_ESTIMATE_BYTES_PER_TOKEN),
+      estimatedTokens: z.number().int().nonnegative(),
+      maxEstimatedTokens: z.literal(
+        Math.ceil(
+          KNOWLEDGE_BROWSE_MAX_RESPONSE_BYTES / KNOWLEDGE_SEARCH_TOKEN_ESTIMATE_BYTES_PER_TOKEN,
+        ),
+      ),
+    }),
+  }),
 });
 export type KnowledgeBrowseResponse = z.infer<typeof KnowledgeBrowseResponse>;

package/src/organization-membership-lifecycle.ts

@@ -0,0 +1,330 @@
+import { z } from "zod";
+import { Permission } from "./permissions";
+
+export const OrganizationMembershipRole = z.enum(["owner", "admin", "member"]);
+export type OrganizationMembershipRole = z.infer<typeof OrganizationMembershipRole>;
+
+export const OrganizationInvitationStatus = z.enum(["pending", "accepted", "revoked", "expired"]);
+export type OrganizationInvitationStatus = z.infer<typeof OrganizationInvitationStatus>;
+
+export const OrganizationInvitation = z.object({
+  id: z.string().uuid(),
+  organizationId: z.string().uuid(),
+  targetEmail: z.string().email(),
+  targetName: z.string().trim().min(1).max(120).nullable().default(null),
+  initialWorkspaceIds: z.array(z.string().uuid()).max(100).default([]),
+  role: OrganizationMembershipRole,
+  status: OrganizationInvitationStatus,
+  revision: z.number().int().positive(),
+  expiresAt: z.string().datetime({ offset: true }),
+  acceptedMembershipId: z.string().uuid().nullable(),
+  createdAt: z.string().datetime({ offset: true }),
+  updatedAt: z.string().datetime({ offset: true }),
+});
+export type OrganizationInvitation = z.infer<typeof OrganizationInvitation>;
+
+export const OrganizationMember = z.object({
+  id: z.string().uuid(),
+  organizationId: z.string().uuid(),
+  subjectId: z.string().min(1).max(1024),
+  name: z.string().min(1).max(1024).nullable().default(null),
+  email: z.string().email().max(320).nullable().default(null),
+  role: OrganizationMembershipRole,
+  status: z.enum(["provisioning", "active", "suspended", "revoked"]),
+  authorizationRevision: z.number().int().positive(),
+  personalWorkspaceId: z.string().uuid().nullable(),
+  revokedAt: z.string().datetime({ offset: true }).nullable(),
+  personalRetentionUntil: z.string().datetime({ offset: true }).nullable(),
+  createdAt: z.string().datetime({ offset: true }),
+  updatedAt: z.string().datetime({ offset: true }),
+});
+export type OrganizationMember = z.infer<typeof OrganizationMember>;
+
+export const OrganizationSummary = z.object({
+  id: z.string().uuid(),
+  name: z.string().trim().min(1).max(120),
+  createdAt: z.string().datetime({ offset: true }),
+  updatedAt: z.string().datetime({ offset: true }),
+});
+export type OrganizationSummary = z.infer<typeof OrganizationSummary>;
+
+export const OrganizationPrivateSessionSettings = z.object({
+  organizationId: z.string().uuid(),
+  enabled: z.boolean(),
+  available: z.boolean(),
+  version: z.number().int().nonnegative(),
+  updatedAt: z.string().datetime({ offset: true }),
+  changed: z.boolean().optional(),
+});
+export type OrganizationPrivateSessionSettings = z.infer<typeof OrganizationPrivateSessionSettings>;
+
+export const UpdateOrganizationPrivateSessionSettingsRequest = z
+  .object({
+    enabled: z.boolean(),
+    expectedVersion: z.number().int().nonnegative(),
+    operationId: z.string().uuid(),
+  })
+  .strict();
+export type UpdateOrganizationPrivateSessionSettingsRequest = z.infer<
+  typeof UpdateOrganizationPrivateSessionSettingsRequest
+>;
+
+export const OrganizationWorkspaceAccessMember = z.object({
+  membershipId: z.string().uuid(),
+  subjectId: z.string().min(1).max(1024),
+  subjectLabel: z.string().min(1).max(1024).nullable(),
+  principalKind: z.enum(["human", "service"]),
+  role: z.string().min(1).max(64),
+  permissions: z.array(z.string().min(1).max(128)),
+  createdAt: z.string().datetime({ offset: true }),
+});
+export type OrganizationWorkspaceAccessMember = z.infer<typeof OrganizationWorkspaceAccessMember>;
+
+export const OrganizationWorkspaceAccess = z.object({
+  id: z.string().uuid(),
+  name: z.string().min(1),
+  slug: z.string().nullable(),
+  createdAt: z.string().datetime({ offset: true }),
+  updatedAt: z.string().datetime({ offset: true }),
+  members: z.array(OrganizationWorkspaceAccessMember).max(1000),
+});
+export type OrganizationWorkspaceAccess = z.infer<typeof OrganizationWorkspaceAccess>;
+
+export const OrganizationAdministrationOverview = z.object({
+  organization: OrganizationSummary,
+  workspaces: z.array(OrganizationWorkspaceAccess).max(500),
+});
+export type OrganizationAdministrationOverview = z.infer<typeof OrganizationAdministrationOverview>;
+
+// Organization-control-plane assignment of an existing active organization
+// member to a shared workspace. The target is a membership rather than an
+// email address: joining the organization and receiving workspace access stay
+// two explicit lifecycle steps, and this surface cannot become a user lookup.
+export const AddOrganizationWorkspaceMemberRequest = z.object({
+  organizationMembershipId: z.string().uuid(),
+  role: z.string().trim().min(1).max(64).optional(),
+  permissions: z.array(Permission).max(128),
+});
+export type AddOrganizationWorkspaceMemberRequest = z.infer<
+  typeof AddOrganizationWorkspaceMemberRequest
+>;
+
+export const CreateOrganizationWorkspaceRequest = z.object({
+  name: z.string().trim().min(1).max(120),
+  slug: z.string().trim().min(1).max(120).nullable().optional(),
+  agentInstructions: z.string().nullable().optional(),
+  operationId: z.string().uuid(),
+});
+export type CreateOrganizationWorkspaceRequest = z.infer<typeof CreateOrganizationWorkspaceRequest>;
+
+export const CreateOrganizationRequest = z.object({
+  name: z.string().trim().min(1).max(120),
+  operationId: z.string().uuid(),
+});
+export type CreateOrganizationRequest = z.infer<typeof CreateOrganizationRequest>;
+
+export const CreateOrganizationResponse = z.object({
+  organization: OrganizationSummary,
+  workspaceId: z.string().uuid(),
+});
+export type CreateOrganizationResponse = z.infer<typeof CreateOrganizationResponse>;
+
+export const UpdateOrganizationNameRequest = z.object({
+  name: z.string().trim().min(1).max(120),
+  expectedUpdatedAt: z.string().datetime({ offset: true }),
+  operationId: z.string().uuid(),
+});
+export type UpdateOrganizationNameRequest = z.infer<typeof UpdateOrganizationNameRequest>;
+
+export const OrganizationRetentionPolicy = z
+  .object({
+    organizationId: z.string().uuid(),
+    mode: z.enum(["retain", "delete_after"]),
+    retentionDays: z.number().int().min(30).max(90).nullable(),
+    version: z.number().int().positive(),
+    updatedAt: z.string().datetime({ offset: true }),
+  })
+  .superRefine((value, context) => {
+    if ((value.mode === "retain") !== (value.retentionDays === null)) {
+      context.addIssue({
+        code: "custom",
+        path: ["retentionDays"],
+        message: "retain requires no duration; delete_after requires a duration",
+      });
+    }
+  });
+export type OrganizationRetentionPolicy = z.infer<typeof OrganizationRetentionPolicy>;
+
+export const OrganizationRetentionDeletionClaim = z.object({
+  organizationId: z.string().uuid(),
+  membershipId: z.string().uuid(),
+  operationId: z.string().uuid(),
+  retentionUntil: z.string().datetime({ offset: true }),
+  claimExpiresAt: z.string().datetime({ offset: true }),
+  personalWorkspaceId: z.string().uuid().nullable(),
+  objectCount: z.number().int().nonnegative(),
+  deletedObjectCount: z.number().int().nonnegative(),
+});
+export type OrganizationRetentionDeletionClaim = z.infer<typeof OrganizationRetentionDeletionClaim>;
+
+export const OrganizationRetentionDeletionObject = z.object({
+  objectKind: z.enum([
+    "file",
+    "session_recording",
+    "browser_state_artifact",
+    "browser_state_upload",
+    "transcription_recording_object",
+    "video_staging_reference",
+    "workspace_artifact_version",
+    "editable_artifact_blob",
+    "workspace_capture_manifest",
+    "workspace_capture_tree_index",
+    "workspace_capture_blob",
+  ]),
+  sourceId: z.string().min(1).max(2048),
+  objectBucket: z.string().min(1).max(1024),
+  objectKey: z.string().min(1).max(4096),
+});
+export type OrganizationRetentionDeletionObject = z.infer<
+  typeof OrganizationRetentionDeletionObject
+>;
+
+export const OrganizationRetentionDatabaseFinalization = z.object({
+  organizationId: z.string().uuid(),
+  membershipId: z.string().uuid(),
+  operationId: z.string().uuid(),
+  outcome: z.literal("cleanup_pending"),
+  objectBucket: z.string().min(1).max(1024),
+  objectCount: z.number().int().nonnegative(),
+  deletedResources: z.record(z.string(), z.number().int().nonnegative()),
+  databaseFinalizedAt: z.string().datetime({ offset: true }),
+});
+export type OrganizationRetentionDatabaseFinalization = z.infer<
+  typeof OrganizationRetentionDatabaseFinalization
+>;
+
+export const OrganizationRetentionDeletionResult = z.object({
+  organizationId: z.string().uuid(),
+  membershipId: z.string().uuid(),
+  operationId: z.string().uuid(),
+  outcome: z.enum(["completed", "already_completed"]),
+  deletedResources: z.record(z.string(), z.number().int().nonnegative()),
+  completedAt: z.string().datetime({ offset: true }),
+});
+export type OrganizationRetentionDeletionResult = z.infer<
+  typeof OrganizationRetentionDeletionResult
+>;
+
+export const OrganizationRetentionDeletionPreview = z.object({
+  membershipId: z.string().uuid(),
+  retentionUntil: z.string().datetime({ offset: true }),
+  personalWorkspaceId: z.string().uuid().nullable(),
+  resourceCount: z.number().int().nonnegative(),
+  objectCount: z.number().int().nonnegative(),
+});
+export type OrganizationRetentionDeletionPreview = z.infer<
+  typeof OrganizationRetentionDeletionPreview
+>;
+
+export const CreateOrganizationInvitationRequest = z.object({
+  email: z.string().email().max(320),
+  name: z.string().trim().min(1).max(120).optional(),
+  initialWorkspaceIds: z.array(z.string().uuid()).max(100).default([]),
+  role: OrganizationMembershipRole.default("member"),
+  expiresAt: z.string().datetime({ offset: true }),
+  operationId: z.string().uuid(),
+});
+export type CreateOrganizationInvitationRequest = z.infer<
+  typeof CreateOrganizationInvitationRequest
+>;
+
+export const AcceptOrganizationInvitationRequest = z.object({
+  expectedRevision: z.number().int().positive(),
+  operationId: z.string().uuid(),
+});
+export type AcceptOrganizationInvitationRequest = z.infer<
+  typeof AcceptOrganizationInvitationRequest
+>;
+
+export const RevokeOrganizationInvitationRequest = AcceptOrganizationInvitationRequest;
+export type RevokeOrganizationInvitationRequest = z.infer<
+  typeof RevokeOrganizationInvitationRequest
+>;
+
+export const OrganizationMemberTransitionKind = z.enum([
+  "change_role",
+  "suspend",
+  "reactivate",
+  "offboard",
+]);
+export type OrganizationMemberTransitionKind = z.infer<typeof OrganizationMemberTransitionKind>;
+
+export const UpdateOrganizationMemberRequest = z
+  .object({
+    kind: OrganizationMemberTransitionKind,
+    role: OrganizationMembershipRole.optional(),
+    expectedAuthorizationRevision: z.number().int().positive(),
+    operationId: z.string().uuid(),
+    reason: z.string().trim().min(1).max(512).optional(),
+  })
+  .superRefine((value, context) => {
+    if ((value.kind === "change_role") !== (value.role !== undefined)) {
+      context.addIssue({
+        code: "custom",
+        path: ["role"],
+        message: "role is required only for change_role",
+      });
+    }
+  });
+export type UpdateOrganizationMemberRequest = z.infer<typeof UpdateOrganizationMemberRequest>;
+
+export const UpdateOrganizationRetentionPolicyRequest = z
+  .object({
+    mode: z.enum(["retain", "delete_after"]),
+    retentionDays: z.number().int().min(30).max(90).nullable(),
+    expectedVersion: z.number().int().positive(),
+    operationId: z.string().uuid(),
+  })
+  .superRefine((value, context) => {
+    if ((value.mode === "retain") !== (value.retentionDays === null)) {
+      context.addIssue({
+        code: "custom",
+        path: ["retentionDays"],
+        message: "retain requires no duration; delete_after requires a duration",
+      });
+    }
+  });
+export type UpdateOrganizationRetentionPolicyRequest = z.infer<
+  typeof UpdateOrganizationRetentionPolicyRequest
+>;
+
+export const ListOrganizationInvitationsResponse = z.object({
+  invitations: z.array(OrganizationInvitation).max(101),
+});
+export const ListOrganizationInvitationsPageQuery = z.object({
+  cursor: z.string().uuid().optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(50),
+});
+export type ListOrganizationInvitationsPageQuery = z.infer<
+  typeof ListOrganizationInvitationsPageQuery
+>;
+export const ListOrganizationInvitationsPageResponse = z.object({
+  invitations: z.array(OrganizationInvitation).max(100),
+  nextCursor: z.string().uuid().nullable(),
+});
+export type ListOrganizationInvitationsPageResponse = z.infer<
+  typeof ListOrganizationInvitationsPageResponse
+>;
+export const AcceptOrganizationInvitationResponse = z.object({
+  invitation: OrganizationInvitation,
+  membership: OrganizationMember,
+});
+export type AcceptOrganizationInvitationResponse = z.infer<
+  typeof AcceptOrganizationInvitationResponse
+>;
+export const ListOrganizationMembersResponse = z.object({
+  members: z.array(OrganizationMember),
+});
+export const ListSelfOrganizationMembershipsResponse = z.object({
+  memberships: z.array(OrganizationMember),
+});

package/src/permissions.ts

@@ -0,0 +1,55 @@
+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",
+  "connections:read",
+  "connections:write",
+  /** @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>;