@opengeni/contracts 0.40.0 → 0.44.1

package/src/index.ts

@@ -1,15 +1,27 @@
 import { z } from "zod";
+import { ScopedKnowledgeScope } from "./scoped-knowledge";
 import {
   boundSessionEventPayload,
   measureSessionEventJson,
   sessionEventJsonBytes,
   type SessionEventBoundarySurface,
 } from "./event-preview";
+import { MemorySlackPublicationDistribution } from "./memory-slack-delivery";
 import { WorkspaceInstructionPolicyRoleKeyInput } from "./workspace-instruction-policies";
 import { ClientResumableVoiceInputConfig } from "./transcription-recordings";
+import { MediaGenerationResult } from "./video-generation";
 
 export * from "./slack-bot-scopes";
+export * from "./atlassian";
 export * from "./connector-destinations";
+export * from "./memory-slack-delivery";
+export * from "./image-generation";
+export * from "./video-generation";
+export * from "./editable-artifacts";
+export * from "./editable-artifact-committed-transaction";
+export * from "./editable-artifact-serialized-commit";
+export * from "./tool-catalog";
+export * from "./interaction";
 
 export {
   CreateWorkspaceArtifactRequest,
@@ -71,6 +83,8 @@ export {
   COMPUTER_SCREENSHOT_MAX_PIXELS,
   COMPUTER_SCREENSHOT_RETENTION_MS,
   COMPUTER_SCREENSHOT_WORKSPACE_QUOTA_BYTES,
+  GENERATED_IMAGE_MAX_BYTES,
+  GENERATED_VIDEO_MAX_BYTES,
   RETAINED_OUTPUT_DEFAULT_PAGE_BYTES,
   RETAINED_OUTPUT_MAX_PAGE_BYTES,
   RETAINED_OUTPUT_RECEIPT_MAX_BYTES,
@@ -81,6 +95,8 @@ export {
   RetainedOutputKind,
   RetainedOutputUnavailableReason,
   retainedArtifactReferenceFromFile,
+  retainedGeneratedImageReferenceFromFile,
+  retainedGeneratedVideoReferenceFromFile,
   retainedScreenshotReferenceFromFile,
   retainedOutputUnavailable,
   resolveRetainedOutputRange,
@@ -88,6 +104,8 @@ export {
   type RetainedArtifactFileInput,
   type RetainedArtifactMetadata,
   type RetainedArtifactReference,
+  type RetainedGeneratedImageArtifactInput,
+  type RetainedGeneratedVideoArtifactInput,
   type RetainedScreenshotArtifactInput,
   type RetainedArtifactUnavailable,
   type RetainedOutputAvailableEvidence,
@@ -101,6 +119,7 @@ export {
   WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION,
   backendForNativeSnapshotProvider,
   decodeNativeSnapshotRef,
+  encodeNativeSnapshotRef,
   parseWorkspaceArchiveDescriptor,
   type NativeSnapshotDescriptor,
   type NativeSnapshotProvider,
@@ -147,6 +166,54 @@ export const SandboxBackend = z.enum([
 ]);
 export type SandboxBackend = z.infer<typeof SandboxBackend>;
 
+// OpenGeni-owned identity carried beside the provider's opaque SDK envelope.
+// Provider serializers intentionally use different keys (`sandboxId`,
+// `devboxId`, `sandboxName`, ...); durable lease logic must not need to learn a
+// new provider's private state shape. Existing envelopes remain readable via
+// the legacy keys below, while every newly-serialized envelope carries this
+// stable field.
+export const OPENGENI_SANDBOX_PROVIDER_INSTANCE_ID_FIELD = "opengeniProviderInstanceId" as const;
+export const SANDBOX_PROVIDER_INSTANCE_ID_FIELDS_BY_BACKEND = {
+  docker: ["containerId"],
+  modal: ["sandboxId"],
+  local: ["workspaceRootPath"],
+  none: [],
+  daytona: ["sandboxId"],
+  runloop: ["devboxId"],
+  e2b: ["sandboxId"],
+  // A Blaxel name is reusable after deletion. The SDK persists a canonical
+  // metadata identity (name + creation timestamp + workspace) specifically to
+  // distinguish a later sandbox created under the same name.
+  blaxel: ["sandboxIdentity"],
+  cloudflare: ["sandboxId"],
+  vercel: ["sandboxId"],
+  selfhosted: ["agentId"],
+} as const satisfies Record<SandboxBackend, readonly string[]>;
+export const LEGACY_SANDBOX_PROVIDER_INSTANCE_ID_FIELDS = [
+  "sandboxId",
+  "devboxId",
+  "sandboxName",
+  "sandboxIdentity",
+  "containerId",
+  "workspaceRootPath",
+  "agentId",
+] as const;
+
+/**
+ * Durable proof that a provider may replace an execution wrapper without
+ * replacing the workspace OpenGeni owns. This is intentionally narrower than
+ * generic provider resume: only a provider adapter that can prove the same
+ * continuity key may consume it, and only a cold->warming owner or teardown
+ * claimant may authorize that replacement.
+ */
+export type SandboxProviderContinuityRecovery = {
+  version: 1;
+  backend: SandboxBackend;
+  kind: "docker_workspace";
+  sourceInstanceId: string;
+  continuityKey: string;
+};
+
 // OS axis. Only "linux" is reachable in v1; macos/windows are seam placeholders.
 export const SandboxOs = z.enum(["linux", "macos", "windows"]);
 export type SandboxOs = z.infer<typeof SandboxOs>;
@@ -217,6 +284,7 @@ export const DESKTOP_STREAM_PORT = 6080;
 // ttyd's default; the box bakes ttyd and launches it on this port. The pty-ws
 // Terminal cell's `url` is the tunnel address resolved against this port.
 export const TERMINAL_STREAM_PORT = 7681;
+export const BROWSER_CONTROL_PORT = 7682;
 
 // The provider capability matrix (sandbox contract PART D + module 03-providers). One row per
 // backend (10 rows). v1 reachable cells are all Linux; macos/windows are seam
@@ -664,7 +732,7 @@ export const Permission = z.enum([
   // Programmatic sandbox -> tool access through the first-party MCP gate. This is
   // intentionally narrow and is never part of first-party MCP defaults; callers
   // must receive it through an explicit delegated `ogd_` mint carrying sessionId.
-  "toolspace:call",
+  "codemode:call",
   "goals:manage",
   // Bring-your-own-compute (M5). enrollments:read lists a workspace's machines;
   // enrollments:manage approves a device-flow enrollment (the LOUD whole-machine
@@ -697,6 +765,7 @@ export type Permission = z.infer<typeof Permission>;
  */
 export const DEFAULT_FIRST_PARTY_MCP_PERMISSIONS = [
   "workspace:read",
+  "files:upload",
   "files:read",
   "documents:search",
   "scheduled_tasks:manage",
@@ -756,11 +825,27 @@ export const FIRST_PARTY_MCP_TOOL_NAMES = [
   "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",
@@ -771,6 +856,18 @@ export const FIRST_PARTY_MCP_TOOL_NAMES = [
   "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",
@@ -789,22 +886,81 @@ export const FIRST_PARTY_MCP_TOOL_NAMES = [
   "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",
+  "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",
 ] as const;
 export const FirstPartyMcpToolName = z.enum(FIRST_PARTY_MCP_TOOL_NAMES);
 export type FirstPartyMcpToolName = z.infer<typeof FirstPartyMcpToolName>;
 
+/**
+ * First-party interaction tools executed inside the frozen attempt rather than
+ * registered on the remote `opengeni` MCP server. They still belong to the
+ * same user-selectable first-party catalog and use the same attempt executor.
+ */
+export const FIRST_PARTY_IN_PROCESS_TOOL_NAMES = [
+  "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",
+] as const satisfies readonly FirstPartyMcpToolName[];
+
+const FIRST_PARTY_IN_PROCESS_TOOL_NAME_SET = new Set<FirstPartyMcpToolName>(
+  FIRST_PARTY_IN_PROCESS_TOOL_NAMES,
+);
+
+/** Exact catalog registered by the remote first-party `opengeni` MCP server. */
+export const FIRST_PARTY_REMOTE_MCP_TOOL_NAMES = FIRST_PARTY_MCP_TOOL_NAMES.filter(
+  (name) => !FIRST_PARTY_IN_PROCESS_TOOL_NAME_SET.has(name),
+) satisfies readonly FirstPartyMcpToolName[];
+
+/** Authored CodeMode paths for the canonical collaborative artifact surface. */
+export const EDITABLE_ARTIFACT_MCP_CODEMODE_PATHS = {
+  editable_artifact_list: ["artifacts", "list"],
+  editable_artifact_create: ["artifacts", "create"],
+  editable_artifact_import: ["artifacts", "import"],
+  editable_artifact_get: ["artifacts", "get"],
+  editable_artifact_inspect: ["artifacts", "inspect"],
+  editable_artifact_apply: ["artifacts", "apply"],
+  editable_artifact_export: ["artifacts", "export"],
+  editable_artifact_export_status: ["artifacts", "exportStatus"],
+} as const satisfies Partial<Record<FirstPartyMcpToolName, readonly [string, string]>>;
+
 /**
  * Connector-wide tools are explicit-only. Ordinary session omission selects
  * the non-connector catalog, while an explicit session policy may still select
  * any catalogued connector tool and remains independently permission-gated.
  */
 export const DEFAULT_FIRST_PARTY_MCP_TOOLS = FIRST_PARTY_MCP_TOOL_NAMES.filter(
-  (name) => !name.startsWith("social_") && !name.startsWith("slack_bot_"),
+  (name) =>
+    !name.startsWith("social_") &&
+    !name.startsWith("x_") &&
+    !name.startsWith("reddit_") &&
+    !name.startsWith("slack_bot_") &&
+    !name.startsWith("atlassian_"),
 ) satisfies readonly FirstPartyMcpToolName[];
 
 export function prefixedMcpToolName(registryId: string, toolName: string): string {
@@ -1220,12 +1376,7 @@ export * from "./transcription-recordings";
 export const CodexCompactionMode = z.enum(["remote_v2", "portable"]);
 export type CodexCompactionMode = z.infer<typeof CodexCompactionMode>;
 
-export const SlackReactionEmojiName = z
-  .string()
-  .trim()
-  .min(1)
-  .max(64)
-  .regex(/^[a-z0-9_+-]+$/, "use the exact Slack emoji name without surrounding colons");
+export const SlackReactionEmojiName = z.literal("genie");
 export type SlackReactionEmojiName = z.infer<typeof SlackReactionEmojiName>;
 
 export const WorkspaceSlackReactionChannelPolicy = z.discriminatedUnion("mode", [
@@ -2086,6 +2237,61 @@ export const UpdateWorkspaceMemberRequest = z.object({
 });
 export type UpdateWorkspaceMemberRequest = z.infer<typeof UpdateWorkspaceMemberRequest>;
 
+export const SlackUserLinkAccessRequestStatus = z.enum([
+  "prepared",
+  "pending",
+  "completed",
+  "denied",
+  "cancelled",
+  "expired",
+]);
+export type SlackUserLinkAccessRequestStatus = z.infer<typeof SlackUserLinkAccessRequestStatus>;
+
+/**
+ * Durable, token-free projection of one signed Slack identity-link intent.
+ * The original bearer and its digest are deliberately absent from every
+ * public response.
+ */
+export const SlackUserLinkAccessRequest = z.object({
+  id: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  workspaceDisplayName: z.string().min(1).max(256).nullable(),
+  subjectLabel: z.string().min(1).max(512).nullable(),
+  status: SlackUserLinkAccessRequestStatus,
+  version: z.number().int().positive(),
+  expiresAt: z.string().datetime({ offset: true }),
+  requestedAt: z.string().datetime({ offset: true }).nullable(),
+  decidedAt: z.string().datetime({ offset: true }).nullable(),
+  completedAt: z.string().datetime({ offset: true }).nullable(),
+  createdAt: z.string().datetime({ offset: true }),
+  updatedAt: z.string().datetime({ offset: true }),
+});
+export type SlackUserLinkAccessRequest = z.infer<typeof SlackUserLinkAccessRequest>;
+
+export const PrepareSlackUserLinkAccessRequest = z.object({
+  linkToken: z.string().min(1).max(2_048),
+});
+export type PrepareSlackUserLinkAccessRequest = z.infer<typeof PrepareSlackUserLinkAccessRequest>;
+
+export const SlackUserLinkAccessMutationRequest = z.object({
+  expectedVersion: z.number().int().positive(),
+  idempotencyKey: z.string().trim().min(1).max(200),
+});
+export type SlackUserLinkAccessMutationRequest = z.infer<typeof SlackUserLinkAccessMutationRequest>;
+
+export const ApproveSlackUserLinkAccessRequest = SlackUserLinkAccessMutationRequest.extend({
+  role: z.string().trim().min(1).max(128).optional(),
+  permissions: z.array(Permission).min(1),
+});
+export type ApproveSlackUserLinkAccessRequest = z.infer<typeof ApproveSlackUserLinkAccessRequest>;
+
+export const ListSlackUserLinkAccessRequestsResponse = z.object({
+  requests: z.array(SlackUserLinkAccessRequest),
+});
+export type ListSlackUserLinkAccessRequestsResponse = z.infer<
+  typeof ListSlackUserLinkAccessRequestsResponse
+>;
+
 export const UsageEventType = z.enum([
   "agent_run.created",
   "agent_run.completed",
@@ -2095,6 +2301,10 @@ export const UsageEventType = z.enum([
   "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) ---
   // Wall-clock seconds a box was warm — the billable warm-time meter. Accrued on
@@ -2133,6 +2343,9 @@ export type InsightsRange = z.infer<typeof InsightsRange>;
 export const InsightsBillingPath = z.enum(["opengeni_credits", "external"]);
 export type InsightsBillingPath = z.infer<typeof InsightsBillingPath>;
 
+export const InsightsPricingSource = z.enum(["configured_list_price", "gateway_reported"]);
+export type InsightsPricingSource = z.infer<typeof InsightsPricingSource>;
+
 export const InsightsModelUsageRow = z.object({
   id: z.string().min(1),
   model: z.string().min(1),
@@ -2142,10 +2355,17 @@ export const InsightsModelUsageRow = z.object({
   inputTokens: z.number().nonnegative(),
   outputTokens: z.number().nonnegative(),
   cachedTokens: z.number().nonnegative(),
+  cacheInputTokens: z.number().nonnegative(),
   cacheWriteTokens: z.number().nonnegative(),
   reasoningTokens: z.number().nonnegative(),
+  totalTokens: z.number().nonnegative(),
+  tokenKnownCalls: z.number().int().nonnegative(),
+  cacheKnownCalls: z.number().int().nonnegative(),
   /** Priced OpenGeni credit $ for this model×provider (from model_call_facts). */
   creditUsd: z.number().nonnegative(),
+  /** Hypothetical provider-rate USD; never an OpenGeni charge. */
+  estimatedProviderUsd: z.number().nonnegative(),
+  estimatedProviderCostKnownCalls: z.number().int().nonnegative(),
 });
 export type InsightsModelUsageRow = z.infer<typeof InsightsModelUsageRow>;
 
@@ -2153,9 +2373,19 @@ export const InsightsSeriesPoint = z.object({
   label: z.string().min(1),
   /** Day-bucketed sum of usage_events.model.cost (workspace-wide) or filtered facts when provider/model set. */
   modelCostUsd: z.number().nonnegative(),
+  /** Day-bucketed hypothetical provider-rate USD for calls with captured pricing. */
+  estimatedProviderUsd: z.number().nonnegative(),
+  estimatedProviderCostKnownCalls: z.number().int().nonnegative(),
   warmSeconds: z.number().nonnegative(),
   inputTokens: z.number().nonnegative(),
+  outputTokens: z.number().nonnegative(),
   cachedTokens: z.number().nonnegative(),
+  cacheInputTokens: z.number().nonnegative(),
+  cacheWriteTokens: z.number().nonnegative(),
+  reasoningTokens: z.number().nonnegative(),
+  totalTokens: z.number().nonnegative(),
+  tokenKnownCalls: z.number().int().nonnegative(),
+  cacheKnownCalls: z.number().int().nonnegative(),
   cacheHitPct: z.number().int().min(0).max(100),
   calls: z.number().int().nonnegative(),
 });
@@ -2178,9 +2408,12 @@ export const InsightsSpendDriver = z.object({
   groupBy: z.enum(["root_session", "schedule"]),
   label: z.string().min(1),
   creditUsd: z.number().nonnegative(),
+  estimatedProviderUsd: z.number().nonnegative(),
+  estimatedProviderCostKnownCalls: z.number().int().nonnegative(),
   tokens: z.number().nonnegative(),
   cacheHitPct: z.number().int().min(0).max(100),
   pctOfCreditUsd: z.number().int().min(0).max(100),
+  pctOfTokens: z.number().int().min(0).max(100),
   deltaUsdVsPrior: z.number(),
 });
 export type InsightsSpendDriver = z.infer<typeof InsightsSpendDriver>;
@@ -2227,18 +2460,48 @@ export const InsightsScheduleRow = z.object({
   fires: z.number().int().nonnegative(),
   /** Null when no facts carry scheduled_task_id for this window. */
   creditUsd: z.number().nonnegative().nullable(),
+  estimatedProviderUsd: z.number().nonnegative().nullable(),
+  estimatedProviderCostKnownCalls: z.number().int().nonnegative().nullable(),
   tokens: z.number().nonnegative().nullable(),
   cacheHitPct: z.number().int().min(0).max(100).nullable(),
   billing: InsightsBillingPath.nullable(),
 });
 export type InsightsScheduleRow = z.infer<typeof InsightsScheduleRow>;
 
+export const InsightsModelCallRow = z.object({
+  id: z.string().uuid(),
+  occurredAt: z.string().datetime(),
+  recordedAt: z.string().datetime(),
+  sessionId: z.string().uuid(),
+  sessionTitle: z.string(),
+  turnId: z.string().uuid(),
+  provider: z.string().min(1),
+  providerApi: z.string().min(1),
+  model: z.string().min(1),
+  billing: InsightsBillingPath,
+  inputTokens: z.number().nonnegative().nullable(),
+  outputTokens: z.number().nonnegative().nullable(),
+  cachedTokens: z.number().nonnegative().nullable(),
+  cacheWriteTokens: z.number().nonnegative().nullable(),
+  reasoningTokens: z.number().nonnegative().nullable(),
+  totalTokens: z.number().nonnegative().nullable(),
+  /** OpenGeni credit price for this call. External calls are always zero. */
+  creditUsd: z.number().nonnegative(),
+  /** Hypothetical provider-rate USD; null when historical pricing is unavailable. */
+  estimatedProviderUsd: z.number().nonnegative().nullable(),
+  pricingSource: InsightsPricingSource.nullable(),
+});
+export type InsightsModelCallRow = z.infer<typeof InsightsModelCallRow>;
+
 export const WorkspaceInsightsSnapshot = z.object({
   range: InsightsRange,
   rangeLabel: z.string().min(1),
   priorLabel: z.string().min(1),
   seriesLabel: z.string().min(1),
   cacheSeriesLabel: z.string().min(1),
+  windowStart: z.string().datetime(),
+  windowEnd: z.string().datetime(),
+  generatedAt: z.string().datetime(),
   /** All ranges/series are UTC. */
   timezone: z.literal("UTC"),
   models: z.array(InsightsModelUsageRow),
@@ -2248,6 +2511,7 @@ export const WorkspaceInsightsSnapshot = z.object({
   depth: z.array(InsightsDepthBucket),
   drivers: z.array(InsightsSpendDriver),
   schedules: z.array(InsightsScheduleRow),
+  recentCalls: z.array(InsightsModelCallRow),
   warmSeconds: z.number().nonnegative(),
   priorWarmSeconds: z.number().nonnegative(),
   warmGroups: z.array(InsightsWarmGroupRow),
@@ -2261,7 +2525,14 @@ export const WorkspaceInsightsSnapshot = z.object({
   /** Model-filterable credit $ from facts (equals workspace when unfiltered, ignoring late-reject drift). */
   creditUsd: z.number().nonnegative(),
   priorCreditUsd: z.number().nonnegative(),
+  /** Hypothetical provider-rate USD for calls whose historical price was captured. */
+  estimatedProviderUsd: z.number().nonnegative(),
+  priorEstimatedProviderUsd: z.number().nonnegative(),
+  estimatedProviderCostKnownCalls: z.number().int().nonnegative(),
+  priorEstimatedProviderCostKnownCalls: z.number().int().nonnegative(),
+  modelCalls: z.number().int().nonnegative(),
   priorInputTokens: z.number().nonnegative(),
+  priorTotalTokens: z.number().nonnegative(),
   priorCacheHitPct: z.number().int().min(0).max(100),
   priorCalls: z.number().int().nonnegative(),
   /** Lifetime workspace topology (not scoped to the selected Insights range). */
@@ -2408,7 +2679,7 @@ export type GitCredentialRepositoryRef = z.infer<typeof GitCredentialRepositoryR
 //     `loadVariableSetForRun` (today decrypted with
 //     `environmentsEncryptionKeyBytes(settings)`).
 //   - MCP credentials: request-time transport headers for connection-backed
-//     servers, shared by normal model tools and Toolspace/Code Mode.
+//     servers, shared by normal model tools and Codemode/Code Mode.
 //
 // In embedded/separate topologies the HOST owns these external connections
 // (its GitHub App, its secret vault + encryption key). When a host binds this
@@ -2691,7 +2962,7 @@ export const McpPersonalConnectionDelegation = z
     ownerSubjectId: z.string().min(1).max(512),
     providerDomain: z.string().min(1).max(2048),
     kind: z.enum(["oauth2", "api_key", "app_install", "delegated"]).optional(),
-    connectionType: z.enum(["mcp", "social"]).optional(),
+    connectionType: z.enum(["mcp", "social", "atlassian"]).optional(),
   })
   .strict();
 export type McpPersonalConnectionDelegation = z.infer<typeof McpPersonalConnectionDelegation>;
@@ -2727,7 +2998,7 @@ export type McpPersonalConnectionSummary = z.infer<typeof McpPersonalConnectionS
 export type McpCredentialsRequest = {
   accountId: string;
   workspaceId: string;
-  /** Immediate session whose model or Toolspace call needs the credential. */
+  /** Immediate session whose model or Codemode call needs the credential. */
   sessionId: string;
   /** Workspace-scoped lineage root for host authorization and binding lookup. */
   rootSessionId: string;
@@ -2740,9 +3011,16 @@ export type McpCredentialsRequest = {
   initiatorContext: TurnInitiatorContext;
   /** Immediate technical caller, retained only as non-authoritative audit context. */
   callerSubjectId?: string;
-  surface: "model" | "toolspace";
+  surface: "model" | "codemode";
   /** Canonical MCP destination that will receive the resolved headers. */
   destinationUrl: string;
+  /**
+   * Credential transport requested by the caller. Omitted means the existing
+   * header-only MCP transport. The additive `http_api` target allows embedding
+   * hosts to return query/cookie API-key placements for local API integrations
+   * without making those placements eligible for a remote MCP request.
+   */
+  credentialTarget?: "mcp" | "http_api";
   serverId: string;
   toolName?: string;
   connectionRef: McpServerConnectionRef;
@@ -2755,6 +3033,13 @@ export type McpCredentialAuthNeededReason =
   | "unsupported_auth"
   | "resource_scope_unavailable";
 
+export type ConnectionCredentialPlacement = {
+  carrier: "header" | "query" | "cookie";
+  name: string;
+  value: string;
+  prefix?: string;
+};
+
 export type McpCredentialResolution =
   | {
       status: "ok";
@@ -2763,6 +3048,12 @@ export type McpCredentialResolution =
       workspaceId: string;
       sessionId: string;
       headers: Record<string, string>;
+      /**
+       * Optional normalized HTTP credential placements. When present, header
+       * placements must exactly match `headers`. Query/cookie placements are
+       * accepted only for a request whose credentialTarget is `http_api`.
+       */
+      placements?: ConnectionCredentialPlacement[];
       connectionId: string;
       providerDomain: string;
       provider?: string;
@@ -2803,7 +3094,7 @@ export type ConnectionCredentialsPort = {
    * Resolve rotating MCP transport credentials at request time. Embedded hosts
    * use this to keep their provider connection as the sole credential source;
    * OpenGeni never requires a duplicate connection record. The same resolver is
-   * used by model-visible MCP tools and the additive Toolspace/Code Mode proxy.
+   * used by model-visible MCP tools and the exact-attempt Codemode projection.
    */
   mcpCredentials?(input: McpCredentialsRequest): Promise<McpCredentialResolution>;
 };
@@ -3098,6 +3389,12 @@ export type FileResourceRef = z.infer<typeof FileResourceRef>;
  * reconstruct the same typed attachment input after a model switch or retry.
  */
 export const MODEL_ATTACHMENT_REFS_FIELD = "opengeni_attachment_refs" as const;
+/**
+ * Structured timeline annotations retained beside the deterministic user-text
+ * projection in canonical history. Provider adapters remove this OpenGeni
+ * extension field; the numbered projection in `content` remains model-visible.
+ */
+export const MODEL_TIMELINE_ANNOTATIONS_FIELD = "opengeni_timeline_annotations" as const;
 
 export const ResourceRef = z.discriminatedUnion("kind", [RepositoryResourceRef, FileResourceRef]);
 export type ResourceRef = z.infer<typeof ResourceRef>;
@@ -3408,6 +3705,56 @@ export const DocumentSearchResponse = z.object({
 });
 export type DocumentSearchResponse = z.infer<typeof DocumentSearchResponse>;
 
+export const IndexedDocumentSource = z.object({
+  kind: KnowledgeSourceKind,
+  uri: z.string().nullable(),
+  externalId: z.string().nullable(),
+  title: z.string().nullable(),
+  author: z.string().nullable(),
+  createdAt: z.string().nullable(),
+  updatedAt: z.string().nullable(),
+  version: z.string().nullable(),
+});
+export type IndexedDocumentSource = z.infer<typeof IndexedDocumentSource>;
+
+export const IndexedDocumentProvenance = z.object({
+  ingestionWorkspaceId: z.string().uuid(),
+  baseId: z.string().uuid(),
+  fileId: z.string().uuid(),
+  authorityKind: DocumentAuthorityKind,
+  authorityWorkspaceId: z.string().uuid().nullable(),
+  authoritySubjectId: z.string().nullable(),
+  createdBy: z.string().nullable(),
+  createdAt: z.string(),
+});
+export type IndexedDocumentProvenance = z.infer<typeof IndexedDocumentProvenance>;
+
+export const IndexedDocumentSummary = z.object({
+  id: z.string().uuid(),
+  title: z.string(),
+  parser: z.string(),
+  chunkCount: z.number().int().nonnegative(),
+  indexedAt: z.string(),
+  summary: z.string().nullable(),
+  topics: z.array(z.string()),
+  source: IndexedDocumentSource,
+  provenance: IndexedDocumentProvenance,
+});
+export type IndexedDocumentSummary = z.infer<typeof IndexedDocumentSummary>;
+
+export const ListIndexedDocumentsRequest = z.object({
+  checkpoint: z.string().min(1).max(1_024).optional(),
+  limit: z.number().int().positive().max(100).default(50),
+});
+export type ListIndexedDocumentsRequest = z.infer<typeof ListIndexedDocumentsRequest>;
+
+export const ListIndexedDocumentsResponse = z.object({
+  documents: z.array(IndexedDocumentSummary),
+  nextCheckpoint: z.string().min(1).max(1_024),
+  hasMore: z.boolean(),
+});
+export type ListIndexedDocumentsResponse = z.infer<typeof ListIndexedDocumentsResponse>;
+
 export const CreateDocumentBaseRequest = z.object({
   name: z.string().min(1),
   description: z.string().optional(),
@@ -3547,6 +3894,7 @@ export const CreateKnowledgeMemoryRequest = z.object({
   createdBySessionId: z.string().uuid().optional(),
   pinned: z.boolean().optional(),
   replacesId: z.string().min(1).optional(),
+  slackPublication: MemorySlackPublicationDistribution.optional(),
 });
 export type CreateKnowledgeMemoryRequest = z.infer<typeof CreateKnowledgeMemoryRequest>;
 
@@ -4161,7 +4509,7 @@ export const SessionAuthorizationSurface = z.enum([
   "core",
   "stream",
   "first_party_mcp",
-  "toolspace",
+  "codemode",
 ]);
 export type SessionAuthorizationSurface = z.infer<typeof SessionAuthorizationSurface>;
 
@@ -4450,7 +4798,7 @@ export const SessionAuthorizationOperation = z.enum([
   "session.viewer.control",
   "session.first_party_mcp.call",
   "session.secret.read",
-  "session.toolspace.call",
+  "session.codemode.call",
   "session.pin.write",
   "session.codex_account.write",
   "session.realtime.start",
@@ -4486,6 +4834,8 @@ export const SessionAuthorizationActor = z.discriminatedUnion("kind", [
     /** Frozen authority that admitted the calling turn. */
     initiator: TurnInitiator,
     initiatorContext: TurnInitiatorContext,
+    /** Durable causal human for delegated/service work; null for pure service work. */
+    initiatingHumanSubjectId: z.string().min(1).max(1024).nullable(),
   }),
 ]);
 export type SessionAuthorizationActor = z.infer<typeof SessionAuthorizationActor>;
@@ -4564,44 +4914,276 @@ export type SessionAuthorizationPort = {
   ): Promise<SessionAuthorizationListScope>;
 };
 
-export const SessionTurn = z.object({
-  id: z.string().uuid(),
-  workspaceId: z.string().uuid(),
-  sessionId: z.string().uuid(),
-  triggerEventId: z.string().uuid(),
-  temporalWorkflowId: z.string(),
-  status: SessionTurnStatus,
-  source: SessionTurnSource,
-  position: z.number().int(),
-  prompt: z.string().min(1),
-  resources: z.array(ResourceRef),
-  tools: z.array(ToolRef),
-  // Omitted/default discovery and explicit `tools: []` are distinct. False
-  // inherits the durable session policy; true replaces it for this turn after
-  // admission proves the selection is a subset.
-  toolsProvided: z.boolean().optional(),
-  model: z.string().min(1),
-  reasoningEffort: ReasoningEffort,
-  latencyMode: LatencyMode.default("standard"),
-  sandboxBackend: SandboxBackend,
-  // Per-turn OS override. NULL = inherit the session's sandboxOs.
-  sandboxOs: SandboxOs.nullable(),
-  metadata: z.record(z.string(), z.unknown()),
-  version: z.number().int().positive(),
-  executionGeneration: z.number().int().nonnegative(),
-  activeAttemptId: z.string().uuid().nullable(),
-  lineage: z.record(z.string(), z.unknown()),
-  initiator: TurnInitiator,
-  initiatorContext: TurnInitiatorContext,
-  /** Secret-safe projection of the exact personal authority frozen on this turn. */
-  personalConnections: z.array(McpPersonalConnectionSummary).default([]),
-  cancelledBy: z.string().nullable(),
-  cancelReason: z.string().nullable(),
-  startedAt: z.string().nullable(),
-  finishedAt: z.string().nullable(),
-  createdAt: z.string(),
-  updatedAt: z.string(),
-});
+export const TIMELINE_ANNOTATION_MAX_COUNT = 12;
+export const TIMELINE_ANNOTATION_QUOTE_MAX_BYTES = 16 * 1024;
+export const TIMELINE_ANNOTATION_NOTE_MAX_BYTES = 2 * 1024;
+export const TIMELINE_ANNOTATION_CONTEXT_MAX_BYTES = 512;
+export const TIMELINE_ANNOTATION_LABEL_MAX_BYTES = 256;
+export const TIMELINE_ANNOTATIONS_MAX_BYTES = 64 * 1024;
+
+export const TimelineAnnotationSourceKind = z.enum([
+  "user_message",
+  "assistant_message",
+  "tool_output",
+]);
+export type TimelineAnnotationSourceKind = z.infer<typeof TimelineAnnotationSourceKind>;
+
+export const TimelineAnnotationSourceEventType = z.enum([
+  "user.message",
+  "agent.message.completed",
+  "agent.toolCall.output",
+]);
+export type TimelineAnnotationSourceEventType = z.infer<typeof TimelineAnnotationSourceEventType>;
+
+function timelineAnnotationUtf8Bytes(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}
+
+function timelineAnnotationBoundedText(maxBytes: number, label: string) {
+  return z.string().superRefine((value, ctx) => {
+    if (timelineAnnotationUtf8Bytes(value) > maxBytes) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `${label} must be at most ${maxBytes} UTF-8 bytes`,
+      });
+    }
+  });
+}
+
+export const TimelineAnnotationSource = z
+  .object({
+    kind: TimelineAnnotationSourceKind,
+    eventId: z.string().uuid(),
+    eventType: TimelineAnnotationSourceEventType,
+    sequence: z.number().int().positive(),
+    turnId: z.string().uuid().nullable(),
+    startOffset: z.number().int().nonnegative(),
+    endOffset: z.number().int().nonnegative(),
+    contextBefore: timelineAnnotationBoundedText(
+      TIMELINE_ANNOTATION_CONTEXT_MAX_BYTES,
+      "annotation source contextBefore",
+    ),
+    contextAfter: timelineAnnotationBoundedText(
+      TIMELINE_ANNOTATION_CONTEXT_MAX_BYTES,
+      "annotation source contextAfter",
+    ),
+    label: timelineAnnotationBoundedText(
+      TIMELINE_ANNOTATION_LABEL_MAX_BYTES,
+      "annotation source label",
+    ).optional(),
+  })
+  .strict()
+  .superRefine((source, ctx) => {
+    if (source.endOffset < source.startOffset) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["endOffset"],
+        message: "annotation source endOffset must not precede startOffset",
+      });
+    }
+    const expectedKind =
+      source.eventType === "user.message"
+        ? "user_message"
+        : source.eventType === "agent.message.completed"
+          ? "assistant_message"
+          : "tool_output";
+    if (source.kind !== expectedKind) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["kind"],
+        message: "annotation source kind does not match eventType",
+      });
+    }
+  });
+export type TimelineAnnotationSource = z.infer<typeof TimelineAnnotationSource>;
+
+export const DraftTimelineAnnotation = z
+  .object({
+    id: z.string().uuid(),
+    source: TimelineAnnotationSource,
+    quote: timelineAnnotationBoundedText(TIMELINE_ANNOTATION_QUOTE_MAX_BYTES, "annotation quote"),
+    note: timelineAnnotationBoundedText(TIMELINE_ANNOTATION_NOTE_MAX_BYTES, "annotation note"),
+  })
+  .strict()
+  .superRefine((annotation, ctx) => {
+    if (!annotation.quote.trim()) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["quote"],
+        message: "annotation quote must contain non-whitespace text",
+      });
+    }
+  });
+export type DraftTimelineAnnotation = z.infer<typeof DraftTimelineAnnotation>;
+
+export const SubmittedTimelineAnnotation = DraftTimelineAnnotation.superRefine(
+  (annotation, ctx) => {
+    if (!annotation.note.trim()) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["note"],
+        message: "annotation note must contain non-whitespace text",
+      });
+    }
+  },
+);
+export type SubmittedTimelineAnnotation = z.infer<typeof SubmittedTimelineAnnotation>;
+
+export const TimelineAnnotation = z
+  .object({
+    id: z.string().uuid(),
+    source: TimelineAnnotationSource,
+    quote: timelineAnnotationBoundedText(TIMELINE_ANNOTATION_QUOTE_MAX_BYTES, "annotation quote"),
+    note: timelineAnnotationBoundedText(
+      TIMELINE_ANNOTATION_NOTE_MAX_BYTES,
+      "annotation note",
+    ).refine((value) => value.trim().length > 0, {
+      message: "annotation note must contain non-whitespace text",
+    }),
+    ordinal: z.number().int().positive(),
+  })
+  .strict();
+export type TimelineAnnotation = z.infer<typeof TimelineAnnotation>;
+
+function timelineAnnotationArray<T extends z.ZodTypeAny>(item: T) {
+  return z
+    .array(item)
+    .max(TIMELINE_ANNOTATION_MAX_COUNT)
+    .superRefine((annotations, ctx) => {
+      const ids = new Set<string>();
+      for (let index = 0; index < annotations.length; index += 1) {
+        const id = (annotations[index] as { id?: unknown }).id;
+        if (typeof id === "string" && ids.has(id)) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: [index, "id"],
+            message: "annotation ids must be unique",
+          });
+        }
+        if (typeof id === "string") ids.add(id);
+      }
+      if (
+        timelineAnnotationUtf8Bytes(JSON.stringify(annotations)) > TIMELINE_ANNOTATIONS_MAX_BYTES
+      ) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `annotations must be at most ${TIMELINE_ANNOTATIONS_MAX_BYTES} UTF-8 bytes`,
+        });
+      }
+    });
+}
+
+export const DraftTimelineAnnotations = timelineAnnotationArray(DraftTimelineAnnotation);
+export type DraftTimelineAnnotations = z.infer<typeof DraftTimelineAnnotations>;
+
+export const SubmittedTimelineAnnotations = timelineAnnotationArray(SubmittedTimelineAnnotation);
+export type SubmittedTimelineAnnotations = z.infer<typeof SubmittedTimelineAnnotations>;
+
+export const TimelineAnnotations = timelineAnnotationArray(TimelineAnnotation).superRefine(
+  (annotations, ctx) => {
+    for (let index = 0; index < annotations.length; index += 1) {
+      if (annotations[index]!.ordinal !== index + 1) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: [index, "ordinal"],
+          message: "annotation ordinals must be contiguous and match array order",
+        });
+      }
+    }
+  },
+);
+export type TimelineAnnotations = z.infer<typeof TimelineAnnotations>;
+
+export function numberTimelineAnnotations(
+  annotations: readonly SubmittedTimelineAnnotation[],
+): TimelineAnnotation[] {
+  return annotations.map((annotation, index) => ({
+    ...annotation,
+    source: { ...annotation.source },
+    ordinal: index + 1,
+  }));
+}
+
+export function renderTimelineAnnotationsForModel(
+  text: string,
+  annotations: readonly TimelineAnnotation[],
+): string {
+  if (annotations.length === 0) return text;
+  const sections = annotations.flatMap((annotation) => [
+    `Annotation ${annotation.ordinal}`,
+    `Source: ${JSON.stringify({
+      kind: annotation.source.kind,
+      eventId: annotation.source.eventId,
+      eventType: annotation.source.eventType,
+      sequence: annotation.source.sequence,
+      turnId: annotation.source.turnId,
+      startOffset: annotation.source.startOffset,
+      endOffset: annotation.source.endOffset,
+      contextBefore: annotation.source.contextBefore,
+      contextAfter: annotation.source.contextAfter,
+      ...(annotation.source.label ? { label: annotation.source.label } : {}),
+    })}`,
+    `Exact quote: ${JSON.stringify(annotation.quote)}`,
+    `User note: ${JSON.stringify(annotation.note)}`,
+  ]);
+  return [
+    ...(text.length > 0 ? [text, ""] : []),
+    "[OpenGeni timeline annotations]",
+    ...sections.flatMap((line, index) =>
+      index > 0 && line.startsWith("Annotation ") ? ["", line] : [line],
+    ),
+  ].join("\n");
+}
+
+export const SessionTurn = z
+  .object({
+    id: z.string().uuid(),
+    workspaceId: z.string().uuid(),
+    sessionId: z.string().uuid(),
+    triggerEventId: z.string().uuid(),
+    temporalWorkflowId: z.string(),
+    status: SessionTurnStatus,
+    source: SessionTurnSource,
+    position: z.number().int(),
+    prompt: z.string(),
+    annotations: TimelineAnnotations.default([]),
+    resources: z.array(ResourceRef),
+    tools: z.array(ToolRef),
+    // Omitted/default discovery and explicit `tools: []` are distinct. False
+    // inherits the durable session policy; true replaces it for this turn after
+    // admission proves the selection is a subset.
+    toolsProvided: z.boolean().optional(),
+    model: z.string().min(1),
+    reasoningEffort: ReasoningEffort,
+    latencyMode: LatencyMode.default("standard"),
+    sandboxBackend: SandboxBackend,
+    // Per-turn OS override. NULL = inherit the session's sandboxOs.
+    sandboxOs: SandboxOs.nullable(),
+    metadata: z.record(z.string(), z.unknown()),
+    version: z.number().int().positive(),
+    executionGeneration: z.number().int().nonnegative(),
+    activeAttemptId: z.string().uuid().nullable(),
+    lineage: z.record(z.string(), z.unknown()),
+    initiator: TurnInitiator,
+    initiatorContext: TurnInitiatorContext,
+    /** Secret-safe projection of the exact personal authority frozen on this turn. */
+    personalConnections: z.array(McpPersonalConnectionSummary).default([]),
+    cancelledBy: z.string().nullable(),
+    cancelReason: z.string().nullable(),
+    startedAt: z.string().nullable(),
+    finishedAt: z.string().nullable(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+  })
+  .superRefine((turn, ctx) => {
+    if (turn.prompt.length === 0 && turn.annotations.length === 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["prompt"],
+        message: "turn prompt or annotations are required",
+      });
+    }
+  });
 export type SessionTurn = z.infer<typeof SessionTurn>;
 
 export const EffectiveControlBlocker = z.object({
@@ -4670,6 +5252,7 @@ export type SessionCommandReceipt = z.infer<typeof SessionCommandReceipt>;
 export const ComposerDraft = z.object({
   revision: z.number().int().nonnegative(),
   text: z.string(),
+  annotations: DraftTimelineAnnotations.default([]),
   resources: z.array(ResourceRef),
   model: z.string().min(1),
   reasoningEffort: ReasoningEffort,
@@ -4711,6 +5294,7 @@ export type DeleteSessionQueueItemRequest = z.infer<typeof DeleteSessionQueueIte
 
 export const SaveComposerDraftRequest = ComposerDraft.pick({
   text: true,
+  annotations: true,
   resources: true,
   model: true,
   reasoningEffort: true,
@@ -4984,6 +5568,7 @@ export const SessionSystemUpdateKind = z.enum([
   "agent_message",
   "agent_steer_instruction",
   "child_terminal_result",
+  "media_generation_result",
 ]);
 export type SessionSystemUpdateKind = z.infer<typeof SessionSystemUpdateKind>;
 
@@ -5028,6 +5613,7 @@ export const SessionSystemUpdatePayload = z.discriminatedUnion("type", [
       status: z.enum(["idle", "failed", "cancelled"]),
     })
     .passthrough(),
+  MediaGenerationResult,
 ]);
 export type SessionSystemUpdatePayload = z.infer<typeof SessionSystemUpdatePayload>;
 
@@ -5259,59 +5845,182 @@ export const RigCheck = z.object({
 });
 export type RigCheck = z.infer<typeof RigCheck>;
 
-export const RigVersion = z.object({
-  id: z.string().uuid(),
-  rigId: z.string().uuid(),
-  version: z.number().int().positive(),
-  image: z.string().nullable(),
-  setupScript: z.string().nullable(),
-  checks: z.array(RigCheck),
-  credentialHooks: z.array(z.string()),
-  defaultVariableSetIds: z.array(z.string().uuid()),
-  changelog: z.string().nullable(),
-  // Attribution: 'user:<subject>' | 'session:<id>' | 'system'.
-  createdBy: z.string().nullable(),
-  active: z.boolean(),
-  createdAt: z.string(),
-});
-export type RigVersion = z.infer<typeof RigVersion>;
-
-export const RigVerificationHealth = z.object({
-  checkHealth: z.enum(["passing", "failing", "unknown"]),
-  lastVerifiedAt: z.string().nullable(),
-});
-export type RigVerificationHealth = z.infer<typeof RigVerificationHealth>;
-
-export const Rig = z.object({
-  id: z.string().uuid(),
-  accountId: z.string().uuid(),
-  workspaceId: z.string().uuid(),
-  name: z.string(),
-  description: z.string().nullable(),
-  createdBy: z.string().nullable(),
-  // The rig's currently-active version (present after create; nullable so a
-  // partial/list read can omit it without a schema change).
-  activeVersion: RigVersion.nullable(),
-  // Summary for the currently active version. null only when there is no active
-  // version; otherwise "unknown" means the active version has no verification.
-  activeVersionHealth: RigVerificationHealth.nullable(),
-  versionCount: z.number().int().nonnegative(),
-  createdAt: z.string(),
-  updatedAt: z.string(),
-});
-export type Rig = z.infer<typeof Rig>;
-
-export const RigChangeKind = z.enum(["setup_append", "definition_edit"]);
-export type RigChangeKind = z.infer<typeof RigChangeKind>;
-
-export const RigChangeStatus = z.enum(["proposed", "verifying", "merged", "rejected", "failed"]);
-export type RigChangeStatus = z.infer<typeof RigChangeStatus>;
+export const RigProviderImageBuildStatus = z.enum(["building", "ready", "failed", "unsupported"]);
+export type RigProviderImageBuildStatus = z.infer<typeof RigProviderImageBuildStatus>;
 
-// A single check's outcome inside a verification run (populated in M4).
-export const RigCheckResult = z.object({
-  name: z.string(),
-  command: z.string(),
-  exitCode: z.number().int().nullable(),
+export const RigProviderImage = z
+  .object({
+    backend: SandboxBackend,
+    provider: z.string().min(1).max(64),
+    status: RigProviderImageBuildStatus,
+    // Exact immutable rig-definition/setup identity used to reject stale image
+    // reuse when a version or its effective base image changes.
+    contentHash: z.string().regex(/^sha256:[0-9a-f]{64}$/u),
+    setupHash: z.string().regex(/^sha256:[0-9a-f]{64}$/u),
+    sourceImage: z.string().max(2048).nullable(),
+    buildRequestId: z.string().uuid(),
+    imageId: z.string().min(1).max(512).nullable(),
+    imageDigest: z.string().min(1).max(512).nullable(),
+    artifactId: z.string().uuid().nullable(),
+    providerBindingKeyHash: z
+      .string()
+      .regex(/^sha256:[0-9a-f]{64}$/u)
+      .nullable(),
+    // Added after provider-image v1 shipped. Absence is retained for rolling
+    // compatibility but means runtime must use logical-image + setup fallback
+    // until an explicit verification cold-boots this exact image.
+    coldBootValidation: z
+      .object({
+        version: z.literal(1),
+        checkedAt: z.string().datetime(),
+      })
+      .optional(),
+    provenance: z.object({
+      kind: z.literal("rig_verification"),
+      targetKind: z.enum(["change", "version"]),
+      targetId: z.string().uuid(),
+    }),
+    startedAt: z.string().datetime(),
+    finishedAt: z.string().datetime().nullable(),
+    error: z
+      .object({
+        code: z.string().min(1).max(120),
+        message: z.string().min(1).max(2000),
+        retryable: z.boolean(),
+      })
+      .nullable(),
+  })
+  .superRefine((value, ctx) => {
+    if (value.status === "ready" && !value.imageId && !value.imageDigest) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["imageId"],
+        message: "ready provider images require an immutable image id or digest",
+      });
+    }
+    if (
+      value.status === "ready" &&
+      value.backend === "modal" &&
+      (value.artifactId === null || value.providerBindingKeyHash === null)
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: [value.artifactId === null ? "artifactId" : "providerBindingKeyHash"],
+        message: "ready Modal provider images require durable artifact ownership and binding",
+      });
+    }
+    if (value.status !== "ready" && value.artifactId !== null) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["artifactId"],
+        message: "only ready provider images may retain a durable artifact",
+      });
+    }
+    if (value.status === "building") {
+      if (value.finishedAt !== null) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["finishedAt"],
+          message: "building provider images cannot be finished",
+        });
+      }
+      if (value.error !== null) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["error"],
+          message: "building provider images cannot have a terminal error",
+        });
+      }
+    } else if (value.finishedAt === null) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["finishedAt"],
+        message: "terminal provider images require a finish timestamp",
+      });
+    }
+    if ((value.status === "failed" || value.status === "unsupported") && value.error === null) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["error"],
+        message: `${value.status} provider images require failure truth`,
+      });
+    }
+    if (value.status === "ready" && value.error !== null) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["error"],
+        message: "ready provider images cannot retain an error",
+      });
+    }
+    if (value.status !== "ready" && value.coldBootValidation !== undefined) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["coldBootValidation"],
+        message: "only ready provider images may retain cold-boot validation",
+      });
+    }
+  });
+export type RigProviderImage = z.infer<typeof RigProviderImage>;
+
+export const RigProviderImages = z.partialRecord(SandboxBackend, RigProviderImage);
+export type RigProviderImages = z.infer<typeof RigProviderImages>;
+
+export const RigVersion = z.object({
+  id: z.string().uuid(),
+  rigId: z.string().uuid(),
+  version: z.number().int().positive(),
+  image: z.string().nullable(),
+  setupScript: z.string().nullable(),
+  checks: z.array(RigCheck),
+  credentialHooks: z.array(z.string()),
+  defaultVariableSetIds: z.array(z.string().uuid()),
+  changelog: z.string().nullable(),
+  // Operational build metadata is version-bound but not part of the immutable
+  // rig definition. Each backend records its own truthful build state.
+  providerImages: RigProviderImages.default({}),
+  // Attribution: 'user:<subject>' | 'session:<id>' | 'system'.
+  createdBy: z.string().nullable(),
+  active: z.boolean(),
+  createdAt: z.string(),
+});
+export type RigVersion = z.infer<typeof RigVersion>;
+
+export const RigVerificationHealth = z.object({
+  checkHealth: z.enum(["passing", "failing", "unknown"]),
+  lastVerifiedAt: z.string().nullable(),
+});
+export type RigVerificationHealth = z.infer<typeof RigVerificationHealth>;
+
+export const Rig = z.object({
+  id: z.string().uuid(),
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  name: z.string(),
+  description: z.string().nullable(),
+  createdBy: z.string().nullable(),
+  // The rig's currently-active version (present after create; nullable so a
+  // partial/list read can omit it without a schema change).
+  activeVersion: RigVersion.nullable(),
+  // Summary for the currently active version. null only when there is no active
+  // version; otherwise "unknown" means the active version has no verification.
+  activeVersionHealth: RigVerificationHealth.nullable(),
+  versionCount: z.number().int().nonnegative(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type Rig = z.infer<typeof Rig>;
+
+export const RigChangeKind = z.enum(["setup_append", "definition_edit"]);
+export type RigChangeKind = z.infer<typeof RigChangeKind>;
+
+export const RigChangeStatus = z.enum(["proposed", "verifying", "merged", "rejected", "failed"]);
+export type RigChangeStatus = z.infer<typeof RigChangeStatus>;
+
+// A single check's outcome inside a verification run (populated in M4).
+export const RigCheckResult = z.object({
+  name: z.string(),
+  command: z.string(),
+  exitCode: z.number().int().nullable(),
   output: z.string().optional(),
 });
 export type RigCheckResult = z.infer<typeof RigCheckResult>;
@@ -5389,26 +6098,112 @@ export const ProposeRigChangeRequest = z.discriminatedUnion("kind", [
 ]);
 export type ProposeRigChangeRequest = z.infer<typeof ProposeRigChangeRequest>;
 
-export const ScheduledTaskStatus = z.enum(["active", "paused"]);
+export const ScheduledTaskStatus = /* @__PURE__ */ z.enum(["active", "paused"]);
 export type ScheduledTaskStatus = z.infer<typeof ScheduledTaskStatus>;
 
-export const ScheduledTaskRunStatus = z.enum(["queued", "dispatched", "failed"]);
+export const ScheduledTaskRunStatus = /* @__PURE__ */ z.enum([
+  "queued",
+  "dispatched",
+  "succeeded",
+  "skipped",
+  "failed",
+]);
 export type ScheduledTaskRunStatus = z.infer<typeof ScheduledTaskRunStatus>;
 
-export const ScheduledTaskRunMode = z.enum([
+export const ScheduledTaskRunMode = /* @__PURE__ */ z.enum([
   "new_session_per_run",
   "reusable_session",
   "existing_session",
 ]);
 export type ScheduledTaskRunMode = z.infer<typeof ScheduledTaskRunMode>;
 
-export const ScheduledTaskOverlapPolicy = z.enum(["allow_concurrent", "skip", "buffer_one"]);
+export const ScheduledTaskOverlapPolicy = /* @__PURE__ */ z.enum([
+  "allow_concurrent",
+  "skip",
+  "buffer_one",
+]);
 export type ScheduledTaskOverlapPolicy = z.infer<typeof ScheduledTaskOverlapPolicy>;
 
-export const ScheduledTaskTriggerType = z.enum(["scheduled", "manual"]);
+export const ScheduledTaskTriggerType = /* @__PURE__ */ z.enum([
+  "scheduled",
+  "manual",
+  "initial",
+  "provider_event",
+  "retry",
+  "repair",
+]);
 export type ScheduledTaskTriggerType = z.infer<typeof ScheduledTaskTriggerType>;
 
-export const ScheduledTaskScheduleSpec = z.discriminatedUnion("type", [
+export const ScheduledTaskActionKind = /* @__PURE__ */ z.enum([
+  "agent_turn",
+  "knowledge_source_sync",
+]);
+export type ScheduledTaskActionKind = z.infer<typeof ScheduledTaskActionKind>;
+
+const KnowledgeSourceSyncPositiveInteger = z.number().int().positive();
+const KnowledgeSourceSyncNonnegativeInteger = z.number().int().nonnegative();
+const KnowledgeSourceSyncZeroInteger = KnowledgeSourceSyncNonnegativeInteger.default(0);
+const KnowledgeSourceSyncUuid = z.string().uuid();
+const KnowledgeSourceSyncSubject = z.string().min(1).max(1024);
+const KnowledgeSourceSyncEnabled = z.boolean().default(true);
+const KnowledgeSourceSyncDisabled = z.boolean().default(false);
+
+export const KnowledgeSourceSyncLimits = /* @__PURE__ */ z.object({
+  maxItems: KnowledgeSourceSyncPositiveInteger.max(10_000).default(500),
+  maxBytes: KnowledgeSourceSyncPositiveInteger.max(5_000_000_000).default(500_000_000),
+  maxFileBytes: KnowledgeSourceSyncPositiveInteger.max(5_000_000_000).default(100_000_000),
+  maxProviderRequests: KnowledgeSourceSyncPositiveInteger.max(10_000).default(1_000),
+  maxElapsedSeconds: KnowledgeSourceSyncPositiveInteger.max(3_600).default(300),
+  maxConcurrency: KnowledgeSourceSyncPositiveInteger.max(32).default(4),
+  maxFailureDetails: KnowledgeSourceSyncPositiveInteger.max(100).default(25),
+});
+export type KnowledgeSourceSyncLimits = z.infer<typeof KnowledgeSourceSyncLimits>;
+
+export const KnowledgeSourceSyncConnectionAuthority = /* @__PURE__ */ z.object({
+  connectionId: KnowledgeSourceSyncUuid,
+  connectionVersion: KnowledgeSourceSyncPositiveInteger,
+  providerDomain: z.string().min(1).max(2048),
+  kind: z.enum(["oauth2", "api_key", "app_install", "delegated"]),
+  ownerSubjectId: KnowledgeSourceSyncSubject,
+});
+export type KnowledgeSourceSyncConnectionAuthority = z.infer<
+  typeof KnowledgeSourceSyncConnectionAuthority
+>;
+
+export const KnowledgeSourceSyncAction = /* @__PURE__ */ z
+  .object({
+    kind: z.literal("knowledge_source_sync"),
+    sourceId: KnowledgeSourceSyncUuid,
+    sourceGeneration: KnowledgeSourceSyncNonnegativeInteger,
+    sourceLifecycleGeneration: KnowledgeSourceSyncPositiveInteger,
+    sourceConfigGeneration: KnowledgeSourceSyncPositiveInteger,
+    controlWorkspaceId: KnowledgeSourceSyncUuid,
+    providerCoordinationKey: z.string().trim().min(1).max(1024),
+    connection: KnowledgeSourceSyncConnectionAuthority,
+    destination: ScopedKnowledgeScope,
+    initiatingSubjectId: KnowledgeSourceSyncSubject,
+    allDescendants: KnowledgeSourceSyncEnabled,
+    limits: KnowledgeSourceSyncLimits.prefault({}),
+  })
+  .strict();
+export type KnowledgeSourceSyncAction = z.infer<typeof KnowledgeSourceSyncAction>;
+
+export const KnowledgeSourceSyncScheduleControl = /* @__PURE__ */ z
+  .object({
+    sourceEnabled: KnowledgeSourceSyncEnabled,
+    connectionPaused: KnowledgeSourceSyncDisabled,
+  })
+  .strict();
+export type KnowledgeSourceSyncScheduleControl = z.infer<typeof KnowledgeSourceSyncScheduleControl>;
+
+export const ScheduledTaskAction = /* @__PURE__ */ z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("agent_turn") }).strict(),
+  KnowledgeSourceSyncAction,
+]);
+export type ScheduledTaskAction = z.infer<typeof ScheduledTaskAction>;
+
+export const ScheduledTaskScheduleSpec = /* @__PURE__ */ z.discriminatedUnion("type", [
+  z.object({ type: z.literal("manual") }).strict(),
   z.object({
     type: z.literal("once"),
     runAt: z.string().datetime({ offset: true }),
@@ -5433,7 +6228,7 @@ export const ScheduledTaskScheduleSpec = z.discriminatedUnion("type", [
 ]);
 export type ScheduledTaskScheduleSpec = z.infer<typeof ScheduledTaskScheduleSpec>;
 
-export const ScheduledTaskAgentConfig = z.object({
+export const ScheduledTaskAgentConfig = /* @__PURE__ */ z.object({
   prompt: z.string().min(1),
   resources: z.array(ResourceRef).default([]),
   tools: z.array(ToolRef).default([]),
@@ -5452,7 +6247,7 @@ export const ScheduledTaskAgentConfig = z.object({
 });
 export type ScheduledTaskAgentConfig = z.infer<typeof ScheduledTaskAgentConfig>;
 
-export const ScheduledTask = z.object({
+export const ScheduledTask = /* @__PURE__ */ z.object({
   id: z.string().uuid(),
   accountId: z.string().uuid(),
   workspaceId: z.string().uuid(),
@@ -5462,6 +6257,7 @@ export const ScheduledTask = z.object({
   temporalScheduleId: z.string(),
   runMode: ScheduledTaskRunMode,
   overlapPolicy: ScheduledTaskOverlapPolicy,
+  action: ScheduledTaskAction.default({ kind: "agent_turn" }),
   agentConfig: ScheduledTaskAgentConfig,
   createdBy: TurnInitiator.default({
     kind: "service",
@@ -5484,7 +6280,52 @@ export const ScheduledTask = z.object({
 });
 export type ScheduledTask = z.infer<typeof ScheduledTask>;
 
-export const ScheduledTaskRun = z.object({
+export const KnowledgeSourceSyncFailure = /* @__PURE__ */ z.object({
+  externalObjectId: KnowledgeSourceSyncSubject,
+  code: z.enum([
+    "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: z.boolean(),
+  message: z.string().min(1).max(1000),
+});
+export type KnowledgeSourceSyncFailure = z.infer<typeof KnowledgeSourceSyncFailure>;
+
+export const KnowledgeSourceSyncRunSummary = /* @__PURE__ */ z.object({
+  phase: z
+    .enum(["queued", "inventory", "transfer", "index", "checkpoint", "completed", "failed"])
+    .default("queued"),
+  scanned: KnowledgeSourceSyncZeroInteger,
+  imported: KnowledgeSourceSyncZeroInteger,
+  unchanged: KnowledgeSourceSyncZeroInteger,
+  skipped: KnowledgeSourceSyncZeroInteger,
+  failed: KnowledgeSourceSyncZeroInteger,
+  bytes: KnowledgeSourceSyncZeroInteger,
+  providerRequests: KnowledgeSourceSyncZeroInteger,
+  elapsedMs: KnowledgeSourceSyncZeroInteger,
+  indexed: KnowledgeSourceSyncZeroInteger,
+  aclPending: KnowledgeSourceSyncZeroInteger,
+  retryable: KnowledgeSourceSyncDisabled,
+  limitReached: z
+    .enum(["items", "bytes", "file_bytes", "provider_requests", "elapsed_time"])
+    .nullable()
+    .default(null),
+  checkpointed: KnowledgeSourceSyncDisabled,
+  reconnectRequired: KnowledgeSourceSyncDisabled,
+  failures: z.array(KnowledgeSourceSyncFailure).max(100).default([]),
+});
+export type KnowledgeSourceSyncRunSummary = z.infer<typeof KnowledgeSourceSyncRunSummary>;
+
+export const ScheduledTaskRun = /* @__PURE__ */ z.object({
   id: z.string().uuid(),
   accountId: z.string().uuid(),
   workspaceId: z.string().uuid(),
@@ -5495,15 +6336,23 @@ export const ScheduledTaskRun = z.object({
   firedAt: z.string(),
   sessionId: z.string().uuid().nullable(),
   triggerEventId: z.string().uuid().nullable(),
+  actionKind: ScheduledTaskActionKind.default("agent_turn"),
+  knowledgeSyncRunId: KnowledgeSourceSyncUuid.nullable().default(null),
+  knowledgeSummary: KnowledgeSourceSyncRunSummary.nullable().default(null),
+  completedAt: z.string().nullable().default(null),
   error: z.string().nullable(),
   createdAt: z.string(),
   updatedAt: z.string(),
 });
 export type ScheduledTaskRun = z.infer<typeof ScheduledTaskRun>;
 
-export const CreateScheduledTaskRequest = withVariableSetIdAlias({
+const CreateAgentScheduledTaskRequest = /* @__PURE__ */ withVariableSetIdAlias({
   name: z.string().min(1),
   schedule: ScheduledTaskScheduleSpec,
+  action: z
+    .object({ kind: z.literal("agent_turn") })
+    .strict()
+    .default({ kind: "agent_turn" }),
   runMode: ScheduledTaskRunMode.default("new_session_per_run"),
   overlapPolicy: ScheduledTaskOverlapPolicy.default("allow_concurrent"),
   targetSessionId: z.string().uuid().nullable().optional(),
@@ -5537,13 +6386,44 @@ export const CreateScheduledTaskRequest = withVariableSetIdAlias({
     });
   }
 });
+
+const CreateKnowledgeSourceSyncScheduledTaskRequest = /* @__PURE__ */ z
+  .object({
+    name: z.string().min(1),
+    schedule: ScheduledTaskScheduleSpec,
+    action: KnowledgeSourceSyncAction,
+    overlapPolicy: z.enum(["skip", "buffer_one"]).default("buffer_one"),
+    status: ScheduledTaskStatus.default("active"),
+    metadata: z.record(z.string(), z.unknown()).default({}),
+  })
+  .strict()
+  .transform((value) => ({
+    ...value,
+    runMode: "new_session_per_run" as const,
+    targetSessionId: null,
+    agentConfig: {
+      prompt: "Knowledge source synchronization",
+      resources: [],
+      tools: [],
+      metadata: {},
+    },
+    variableSetId: null,
+    environmentId: null,
+    rigId: null,
+  }));
+
+export const CreateScheduledTaskRequest = /* @__PURE__ */ z.union([
+  CreateKnowledgeSourceSyncScheduledTaskRequest,
+  CreateAgentScheduledTaskRequest,
+]);
 export type CreateScheduledTaskRequest = z.infer<typeof CreateScheduledTaskRequest>;
 
-export const UpdateScheduledTaskRequest = withVariableSetIdAlias({
+export const UpdateScheduledTaskRequest = /* @__PURE__ */ withVariableSetIdAlias({
   name: z.string().min(1).optional(),
   schedule: ScheduledTaskScheduleSpec.optional(),
   runMode: ScheduledTaskRunMode.optional(),
   overlapPolicy: ScheduledTaskOverlapPolicy.optional(),
+  action: ScheduledTaskAction.optional(),
   targetSessionId: z.string().uuid().nullable().optional(),
   agentConfig: ScheduledTaskAgentConfig.optional(),
   status: ScheduledTaskStatus.optional(),
@@ -5729,11 +6609,86 @@ function isSafePackSkillRelativePath(path: string): boolean {
     .every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
 }
 
-const CapabilityPackVariableSet = z.object({
-  description: z.string().min(1),
-  requiredVariables: z.array(VariableSetVariableName).default([]),
-  required: z.boolean().default(false),
-});
+const CapabilityPackVariableSet = z
+  .object({
+    description: z.string().min(1).max(2048),
+    requiredVariables: z.array(VariableSetVariableName).max(256).default([]),
+    required: z.boolean().default(false),
+  })
+  .strict();
+
+const CapabilityPackComponentKey = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(/^[a-z0-9](?:[a-z0-9._/-]*[a-z0-9])?$/);
+
+const CapabilityPackInstanceKey = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(/^[a-z0-9](?:[a-z0-9._/-]*[a-z0-9])?$/);
+
+/**
+ * Immutable requirements adopted by a Pack installation. The manifest names
+ * portable identities; installation resolves them to exact workspace-local
+ * component rows and records Pack ownership in the shared component ledger.
+ */
+export const CapabilityPackComponentReference = z.discriminatedUnion("kind", [
+  z
+    .object({
+      key: CapabilityPackComponentKey,
+      kind: z.literal("plugin"),
+      pluginKey: z.string().min(1).max(200),
+      version: z.string().min(1).max(128),
+      manifestDigest: z.string().regex(/^[0-9a-f]{64}$/),
+      required: z.boolean().default(true),
+    })
+    .strict(),
+  z
+    .object({
+      key: CapabilityPackComponentKey,
+      kind: z.literal("skill"),
+      capabilityId: z.string().min(1).max(512),
+      contentSha256: z.string().regex(/^[0-9a-f]{64}$/),
+      required: z.boolean().default(true),
+    })
+    .strict(),
+  z
+    .object({
+      key: CapabilityPackComponentKey,
+      kind: z.literal("integration"),
+      capabilityId: z.string().min(1).max(512),
+      instanceKey: CapabilityPackInstanceKey,
+      revisionId: z.string().min(1).max(512),
+      contentSha256: z.string().regex(/^[0-9a-f]{64}$/),
+      required: z.boolean().default(true),
+    })
+    .strict(),
+  z
+    .object({
+      key: CapabilityPackComponentKey,
+      kind: z.literal("feature"),
+      capabilityId: z.string().min(1).max(512),
+      instanceKey: CapabilityPackInstanceKey,
+      featureKey: z.string().min(1).max(200),
+      bindingKey: CapabilityPackInstanceKey,
+      configDigest: z.string().regex(/^[0-9a-f]{64}$/),
+      required: z.boolean().default(true),
+    })
+    .strict(),
+]);
+export type CapabilityPackComponentReference = z.infer<typeof CapabilityPackComponentReference>;
+
+export const CapabilityPackRigRequirement = z
+  .object({
+    description: z.string().min(1).max(2048).optional(),
+    required: z.boolean().default(true),
+    rigId: z.string().uuid().optional(),
+    requireVerified: z.boolean().default(false),
+  })
+  .strict();
+export type CapabilityPackRigRequirement = z.infer<typeof CapabilityPackRigRequirement>;
 
 export const CapabilityPack = z.preprocess(
   (input) => {
@@ -5763,15 +6718,19 @@ export const CapabilityPack = z.preprocess(
   },
   z
     .object({
-      id: z.string().min(1),
-      name: z.string().min(1),
-      description: z.string().min(1),
-      role: z.string().min(1),
-      category: z.string().min(1),
-      version: z.string().min(1),
-      // Container image ref (digest-pinned recommended) the pack's sessions run
-      // in. At most one enabled pack per workspace may declare one; with none,
-      // sessions use the deployment-wide image settings.
+      id: z
+        .string()
+        .min(1)
+        .max(100)
+        .regex(/^[a-z0-9](?:[a-z0-9._/-]*[a-z0-9])?$/),
+      name: z.string().min(1).max(200),
+      description: z.string().min(1).max(4096),
+      role: z.string().min(1).max(128),
+      category: z.string().min(1).max(128),
+      version: z.string().min(1).max(128),
+      // Legacy manifest compatibility. V2 installation resolves this image to
+      // an explicit Rig requirement; the Pack no longer changes workspace
+      // runtime settings directly.
       sandboxImage: z.string().trim().min(1).max(512).optional(),
       // Optional provider-native immutable identities for the exact logical
       // sandboxImage above. These avoid re-importing a private registry image on
@@ -5791,7 +6750,8 @@ export const CapabilityPack = z.preprocess(
         })
         .strict()
         .optional(),
-      // Skills delivered into the sandbox skill index when the pack is enabled.
+      // Legacy inline Skills are migrated into immutable Skill components by
+      // the V2 Pack installer. They are not loaded directly by V2 runtime.
       skills: z
         .array(CapabilityPackSkill)
         .max(32)
@@ -5810,6 +6770,8 @@ export const CapabilityPack = z.preprocess(
           });
         })
         .default([]),
+      components: z.array(CapabilityPackComponentReference).max(128).default([]),
+      rig: CapabilityPackRigRequirement.optional(),
       tools: z.array(ToolRef).default([]),
       connectors: z.array(CapabilityPackConnector).default([]),
       knowledge: z.array(CapabilityPackKnowledge).default([]),
@@ -5818,6 +6780,28 @@ export const CapabilityPack = z.preprocess(
       metadata: z.record(z.string(), z.unknown()).default({}),
     })
     .superRefine((pack, ctx) => {
+      const componentKeys = new Set<string>();
+      pack.components.forEach((component, index) => {
+        if (componentKeys.has(component.key)) {
+          ctx.addIssue({
+            code: "custom",
+            message: `duplicate Pack component key: ${component.key}`,
+            path: ["components", index, "key"],
+          });
+        }
+        componentKeys.add(component.key);
+      });
+      pack.skills.forEach((skill, index) => {
+        const key = `inline-skill/${skill.name.toLowerCase()}`;
+        if (componentKeys.has(key)) {
+          ctx.addIssue({
+            code: "custom",
+            message: `Pack component key conflicts with inline Skill ${skill.name}: ${key}`,
+            path: ["skills", index, "name"],
+          });
+        }
+        componentKeys.add(key);
+      });
       if (!pack.sandboxProviderImages?.modal) {
         return;
       }
@@ -5855,7 +6839,12 @@ export const WorkspaceRegisteredPack = z.object({
 });
 export type WorkspaceRegisteredPack = z.infer<typeof WorkspaceRegisteredPack>;
 
-export const PackInstallationStatus = z.enum(["active", "disabled"]);
+export const PackInstallationStatus = z.enum([
+  "installing",
+  "active",
+  "needs_attention",
+  "disabled",
+]);
 export type PackInstallationStatus = z.infer<typeof PackInstallationStatus>;
 
 export const PackInstallation = z.object({
@@ -5864,6 +6853,14 @@ export const PackInstallation = z.object({
   workspaceId: z.string().uuid(),
   packId: z.string().min(1),
   status: PackInstallationStatus,
+  version: z.number().int().positive(),
+  manifestSnapshot: CapabilityPack.nullable(),
+  manifestDigest: z
+    .string()
+    .regex(/^[0-9a-f]{64}$/)
+    .nullable(),
+  selectedRigId: z.string().uuid().nullable(),
+  installedBySubjectId: z.string().min(1).max(1024).nullable(),
   metadata: z.record(z.string(), z.unknown()),
   enabledAt: z.string(),
   updatedAt: z.string(),
@@ -5877,6 +6874,116 @@ export const EnablePackRequest = withVariableSetIdAlias({
 });
 export type EnablePackRequest = z.infer<typeof EnablePackRequest>;
 
+export const PackComponentResolutionStatus = z.enum(["ready", "missing", "mismatch"]);
+export type PackComponentResolutionStatus = z.infer<typeof PackComponentResolutionStatus>;
+
+export const PackComponentResolution = z
+  .object({
+    key: CapabilityPackComponentKey,
+    kind: z.enum(["plugin", "skill", "integration", "feature", "inline_skill"]),
+    capabilityId: z.string().min(1).max(512),
+    required: z.boolean(),
+    status: PackComponentResolutionStatus,
+    expectedDigest: z.string().regex(/^[0-9a-f]{64}$/),
+    actualDigest: z
+      .string()
+      .regex(/^[0-9a-f]{64}$/)
+      .nullable(),
+    resolvedId: z.string().min(1).max(512).nullable(),
+    label: z.string().min(1).max(200),
+  })
+  .strict();
+export type PackComponentResolution = z.infer<typeof PackComponentResolution>;
+
+export const PackRigResolution = z
+  .object({
+    required: z.boolean(),
+    status: z.enum(["not_required", "ready", "missing", "mismatch", "unverified"]),
+    requestedRigId: z.string().uuid().nullable(),
+    rigId: z.string().uuid().nullable(),
+    rigVersionId: z.string().uuid().nullable(),
+    name: z.string().min(1).max(200).nullable(),
+    image: z.string().min(1).max(512).nullable(),
+  })
+  .strict();
+export type PackRigResolution = z.infer<typeof PackRigResolution>;
+
+export const PreviewPackInstallationRequest = z
+  .object({
+    rigId: z.string().uuid().optional(),
+    variableSetId: z.string().uuid().optional(),
+  })
+  .strict();
+export type PreviewPackInstallationRequest = z.infer<typeof PreviewPackInstallationRequest>;
+
+export const PackInstallationPreview = z
+  .object({
+    packId: z.string().min(1),
+    packVersion: z.string().min(1),
+    manifestDigest: z.string().regex(/^[0-9a-f]{64}$/),
+    installationVersion: z.number().int().positive().nullable(),
+    action: z.enum(["install", "update", "repair"]),
+    ready: z.boolean(),
+    blockers: z.array(z.string().min(1).max(500)).max(256),
+    components: z.array(PackComponentResolution).max(160),
+    rig: PackRigResolution,
+    variableSetId: z.string().uuid().nullable(),
+    legacyInlineSkillCount: z.number().int().nonnegative().max(32),
+    legacySandboxImage: z.string().min(1).max(512).nullable(),
+  })
+  .strict();
+export type PackInstallationPreview = z.infer<typeof PackInstallationPreview>;
+
+export const InstallPackRequest = z
+  .object({
+    expectedManifestDigest: z.string().regex(/^[0-9a-f]{64}$/),
+    expectedInstallationVersion: z.number().int().positive().optional(),
+    rigId: z.string().uuid().optional(),
+    variableSetId: z.string().uuid().optional(),
+    idempotencyKey: z.string().uuid(),
+    metadata: z.record(z.string(), z.unknown()).default({}),
+  })
+  .strict();
+export type InstallPackRequest = z.infer<typeof InstallPackRequest>;
+
+export const PackUninstallPreview = z
+  .object({
+    packId: z.string().min(1),
+    installed: z.boolean(),
+    installationVersion: z.number().int().positive().nullable(),
+    components: z
+      .array(
+        z
+          .object({
+            key: CapabilityPackComponentKey,
+            kind: z.enum(["plugin", "skill", "integration", "feature", "inline_skill"]),
+            capabilityId: z.string().min(1).max(512),
+            retainedByOtherOwners: z.boolean(),
+          })
+          .strict(),
+      )
+      .max(160),
+  })
+  .strict();
+export type PackUninstallPreview = z.infer<typeof PackUninstallPreview>;
+
+export const UninstallPackRequest = z
+  .object({
+    expectedInstallationVersion: z.number().int().positive(),
+    idempotencyKey: z.string().uuid(),
+  })
+  .strict();
+export type UninstallPackRequest = z.infer<typeof UninstallPackRequest>;
+
+export const UninstallPackResult = z
+  .object({
+    packId: z.string().min(1),
+    status: z.enum(["not_installed", "uninstalled"]),
+    retainedComponents: z.array(z.string().min(1).max(512)).max(160),
+  })
+  .strict();
+export type UninstallPackResult = z.infer<typeof UninstallPackResult>;
+
 export const SocialProvider = z.enum([
   "x",
   "reddit",
@@ -6110,6 +7217,38 @@ export const OpenGeniSlackBotInstallStart = z.object({
 });
 export type OpenGeniSlackBotInstallStart = z.infer<typeof OpenGeniSlackBotInstallStart>;
 
+export const SlackInstallationBindingState = z.enum(["active", "quarantined"]);
+export type SlackInstallationBindingState = z.infer<typeof SlackInstallationBindingState>;
+
+export const SlackInstallationBinding = z.object({
+  id: z.string().uuid(),
+  accountId: z.string().uuid(),
+  accountName: z.string().min(1),
+  workspaceId: z.string().uuid(),
+  workspaceName: z.string().min(1),
+  connectionId: z.string().uuid(),
+  connectionStatus: ConnectionStatus,
+  connectionVersion: z.number().int().positive(),
+  slackTeamId: z.string().min(1).max(64),
+  slackTeamName: z.string().min(1).max(256),
+  botId: z.string().min(1).max(64),
+  botUserId: z.string().min(1).max(64),
+  botDisplayName: z.literal("OpenGeni"),
+  state: SlackInstallationBindingState,
+  quarantineReason: z.string().min(1).nullable(),
+  version: z.number().int().positive(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type SlackInstallationBinding = z.infer<typeof SlackInstallationBinding>;
+
+export const ListSlackInstallationBindingsResponse = z.object({
+  bindings: z.array(SlackInstallationBinding),
+});
+export type ListSlackInstallationBindingsResponse = z.infer<
+  typeof ListSlackInstallationBindingsResponse
+>;
+
 export const UpdateConnectionRequest = z.object({
   providerDomain: z.string().min(1).optional(),
   subjectId: z.string().min(1).nullable().optional(),
@@ -6201,176 +7340,914 @@ export const CapabilitySource = z.enum([
 ]);
 export type CapabilitySource = z.infer<typeof CapabilitySource>;
 
-export const CapabilityInstallationStatus = z.enum(["active", "disabled"]);
-export type CapabilityInstallationStatus = z.infer<typeof CapabilityInstallationStatus>;
+export const CapabilityInstallationStatus = z.enum(["active", "disabled"]);
+export type CapabilityInstallationStatus = z.infer<typeof CapabilityInstallationStatus>;
+
+export const CapabilityCatalogAuthKind = z.enum(["oauth2", "api_key", "none", "unknown"]);
+export type CapabilityCatalogAuthKind = z.infer<typeof CapabilityCatalogAuthKind>;
+
+export const CapabilityCatalogTier = z.enum(["verified", "community"]);
+export type CapabilityCatalogTier = z.infer<typeof CapabilityCatalogTier>;
+
+/**
+ * User-facing lifecycle truth for the Capabilities control center. This is a
+ * read-model projection only: each action is still executed by the owning
+ * Plugin, Integration, Connection, Skill, or Pack domain.
+ */
+export const CapabilityLifecycleStatus = z.enum([
+  "available",
+  "installed",
+  "connected",
+  "ready",
+  "needs_attention",
+  "unavailable",
+  "managed",
+]);
+export type CapabilityLifecycleStatus = z.infer<typeof CapabilityLifecycleStatus>;
+
+export const CapabilityReadiness = z.enum(["ready", "setup_required", "attention", "unavailable"]);
+export type CapabilityReadiness = z.infer<typeof CapabilityReadiness>;
+
+export const CapabilityAction = z.enum([
+  "install",
+  "connect",
+  "configure",
+  "update",
+  "repair",
+  "disconnect",
+  "uninstall",
+  "inspect",
+]);
+export type CapabilityAction = z.infer<typeof CapabilityAction>;
+
+export const CapabilityLifecycle = z.object({
+  status: CapabilityLifecycleStatus,
+  readiness: CapabilityReadiness,
+  detail: z.string().nullable().default(null),
+  managedBy: z.enum(["deployment", "platform", "workspace"]).nullable().default(null),
+});
+export type CapabilityLifecycle = z.infer<typeof CapabilityLifecycle>;
+
+export const CapabilityRuntime = z.object({
+  available: z.boolean().default(false),
+  mcpServerId: z.string().min(1).optional(),
+  transport: z.string().min(1).optional(),
+  notes: z.string().nullable().default(null),
+  // Registry exposure provenance is server-derived and contains no endpoint or
+  // credential material.
+  catalogTrust: z
+    .object({
+      state: z.enum(["trusted", "legacy_active", "unverified"]),
+      reason: z.enum([
+        "trusted_source",
+        "verified_probe",
+        "active_installation_compatibility",
+        "missing_verification",
+      ]),
+    })
+    .optional(),
+});
+export type CapabilityRuntime = z.infer<typeof CapabilityRuntime>;
+
+export const CapabilityCatalogItem = z.object({
+  id: z.string().min(1),
+  accountId: z.string().uuid().optional(),
+  workspaceId: z.string().uuid().optional(),
+  kind: CapabilityKind,
+  source: CapabilitySource,
+  name: z.string().min(1),
+  description: z.string().nullable().default(null),
+  category: z.string().min(1).default("custom"),
+  tags: z.array(z.string().min(1)).default([]),
+  homepageUrl: z.string().url().nullable().default(null),
+  endpointUrl: z.string().url().nullable().default(null),
+  installUrl: z.string().url().nullable().default(null),
+  authModel: z.string().min(1).nullable().default(null),
+  providerDomain: z.string().min(1).nullable().default(null),
+  surfaceType: z.string().min(1).nullable().default(null),
+  transport: z.string().min(1).nullable().default(null),
+  mcpUrl: z.string().url().nullable().default(null),
+  authKind: CapabilityCatalogAuthKind.nullable().default(null),
+  credentialFacts: z.array(z.record(z.string(), z.unknown())).default([]),
+  tier: CapabilityCatalogTier.nullable().default(null),
+  provenance: z.string().min(1).nullable().default(null),
+  logoAssetPath: z.string().min(1).nullable().default(null),
+  importBatchId: z.string().uuid().nullable().default(null),
+  stale: z.boolean().default(false),
+  staleAt: z.string().nullable().default(null),
+  tools: z.array(ToolRef).default([]),
+  runtime: CapabilityRuntime.default({ available: false, notes: null }),
+  lifecycle: CapabilityLifecycle.default({
+    status: "available",
+    readiness: "setup_required",
+    detail: null,
+    managedBy: null,
+  }),
+  actions: z.array(CapabilityAction).default([]),
+  /**
+   * @deprecated Compatibility projection for existing clients. New surfaces
+   * must use lifecycle and actions rather than treating every type as an
+   * enable/disable toggle.
+   */
+  enabled: z.boolean().default(false),
+  /** @deprecated Compatibility explanation paired with enabled. */
+  enabledReason: z.string().nullable().default(null),
+  // The non-secret connection binding stored with an enabled installation.
+  // Workspace refs retain an exact row id. Subject refs deliberately omit it:
+  // each caller resolves their own visible row by provider/kind at runtime.
+  connectionRef: z
+    .object({
+      connectionId: z.string().min(1).optional(),
+      providerDomain: z.string().min(1),
+      kind: z.string().min(1),
+      subjectScope: z.enum(["workspace", "subject"]).optional(),
+    })
+    .nullable()
+    .default(null),
+  metadata: z.record(z.string(), z.unknown()).default({}),
+  createdAt: z.string().optional(),
+  updatedAt: z.string().optional(),
+});
+export type CapabilityCatalogItem = z.infer<typeof CapabilityCatalogItem>;
+
+/**
+ * Shared trust gate for catalog visibility and runtime selection. Registry rows
+ * remain durable for provenance and audit, but only a reviewed real-MCP probe
+ * with known authentication is exposable. API-key rows additionally need a
+ * machine-actionable header contract; prose credential instructions are not a
+ * runtime contract and must fail closed.
+ */
+export function capabilityCatalogItemIsTrustedForExposure(
+  item: Pick<CapabilityCatalogItem, "source" | "stale" | "authKind" | "metadata">,
+): boolean {
+  if (item.stale) return false;
+  if (item.source !== "registry") return true;
+  const probe = item.metadata.mcpProbe;
+  if (!probe || typeof probe !== "object" || Array.isArray(probe)) return false;
+  if ((probe as Record<string, unknown>).status !== "real") return false;
+  if (item.authKind === null || item.authKind === "unknown") return false;
+  if (item.authKind !== "api_key") return true;
+  const contract = item.metadata.authContract;
+  if (!contract || typeof contract !== "object" || Array.isArray(contract)) return false;
+  const record = contract as Record<string, unknown>;
+  return (
+    typeof record.headerName === "string" &&
+    /^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/.test(record.headerName) &&
+    typeof record.scheme === "string" &&
+    record.scheme.trim().length > 0
+  );
+}
+
+export const CapabilityInstallation = z.object({
+  id: z.string().uuid(),
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  capabilityId: z.string().min(1),
+  kind: CapabilityKind,
+  status: CapabilityInstallationStatus,
+  config: z.record(z.string(), z.unknown()),
+  metadata: z.record(z.string(), z.unknown()),
+  enabledAt: z.string(),
+  updatedAt: z.string(),
+});
+export type CapabilityInstallation = z.infer<typeof CapabilityInstallation>;
+
+export const CreateCapabilityCatalogItemRequest = z.object({
+  id: z.string().min(1).optional(),
+  kind: CapabilityKind.exclude(["pack"]),
+  source: CapabilitySource.default("manual"),
+  name: z.string().min(1),
+  description: z.string().min(1).optional(),
+  category: z.string().min(1).default("custom"),
+  tags: z.array(z.string().min(1)).default([]),
+  homepageUrl: z.string().url().optional(),
+  endpointUrl: z.string().url().optional(),
+  installUrl: z.string().url().optional(),
+  authModel: z.string().min(1).optional(),
+  metadata: z.record(z.string(), z.unknown()).default({}),
+});
+export type CreateCapabilityCatalogItemRequest = z.infer<typeof CreateCapabilityCatalogItemRequest>;
+
+export const EnableCapabilityRequest = withVariableSetIdAlias({
+  config: z.record(z.string(), z.unknown()).default({}),
+  metadata: z.record(z.string(), z.unknown()).default({}),
+  connectionRef: McpServerConnectionRef.optional(),
+  /**
+   * Credential headers for remote MCP capabilities (for example an
+   * Authorization bearer token). Values are encrypted at rest with the
+   * workspace-variable-sets key, injected only into the runtime MCP client,
+   * and never returned by the API — responses expose header names only.
+   */
+  headers: z.record(z.string(), z.string()).default({}),
+  /**
+   * Initial variableSet attachment for kind=pack capabilities. Mirrors the
+   * dedicated POST /packs/:id/enable body: required to enable an
+   * variableSet.required pack through the unified capability-enable path,
+   * optional otherwise. Ignored by non-pack capabilities.
+   */
+  variableSetId: z.string().uuid().optional(),
+  environmentId: z.string().uuid().optional(),
+});
+export type EnableCapabilityRequest = z.infer<typeof EnableCapabilityRequest>;
+
+export const CapabilityCatalogResponse = z.object({
+  items: z.array(CapabilityCatalogItem),
+  installations: z.array(CapabilityInstallation),
+});
+export type CapabilityCatalogResponse = z.infer<typeof CapabilityCatalogResponse>;
+
+export const DiscoverMcpCapabilitiesResponse = z.object({
+  items: z.array(CapabilityCatalogItem),
+  source: z.literal("official_mcp_registry"),
+  sourceUrl: z.string().url(),
+});
+export type DiscoverMcpCapabilitiesResponse = z.infer<typeof DiscoverMcpCapabilitiesResponse>;
+
+export const SkillImportSource = z.enum(["github", "skills_sh"]);
+export type SkillImportSource = z.infer<typeof SkillImportSource>;
+
+export const PreviewSkillImportRequest = z.object({
+  url: z.string().url().max(2048),
+});
+export type PreviewSkillImportRequest = z.infer<typeof PreviewSkillImportRequest>;
+
+export const SkillImportFileSummary = z.object({
+  path: z.string().min(1).max(1024),
+  byteSize: z.number().int().nonnegative().max(262144),
+  contentSha256: z.string().regex(/^[0-9a-f]{64}$/),
+});
+export type SkillImportFileSummary = z.infer<typeof SkillImportFileSummary>;
+
+export const SkillImportPreview = z.object({
+  source: SkillImportSource,
+  sourceUrl: z.string().url(),
+  repositoryUrl: z.string().url(),
+  owner: z.string().min(1).max(100),
+  repository: z.string().min(1).max(100),
+  sourcePath: z.string().min(1).max(1024),
+  sourceCommit: z.string().regex(/^[0-9a-f]{40,64}$/),
+  name: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/),
+  description: z.string().min(1).max(2048),
+  contentSha256: z.string().regex(/^[0-9a-f]{64}$/),
+  totalBytes: z.number().int().positive().max(1048576),
+  files: z.array(SkillImportFileSummary).min(1).max(128),
+  warnings: z.array(z.string().min(1).max(500)).max(32).default([]),
+  installed: z.boolean().default(false),
+  installationVersion: z.number().int().positive().nullable().default(null),
+});
+export type SkillImportPreview = z.infer<typeof SkillImportPreview>;
+
+export const InstallSkillRequest = z.object({
+  url: z.string().url().max(2048),
+  expectedSourceCommit: z.string().regex(/^[0-9a-f]{40,64}$/),
+  expectedContentSha256: z.string().regex(/^[0-9a-f]{64}$/),
+  expectedInstallationVersion: z.number().int().positive().optional(),
+});
+export type InstallSkillRequest = z.infer<typeof InstallSkillRequest>;
+
+export const InstalledSkill = z.object({
+  capabilityId: z.string().min(1),
+  pluginId: z.string().uuid(),
+  pluginVersionId: z.string().uuid(),
+  facetId: z.string().uuid(),
+  pluginInstallationId: z.string().uuid(),
+  facetInstallationId: z.string().uuid(),
+  installationVersion: z.number().int().positive(),
+  source: SkillImportSource,
+  sourceUrl: z.string().url(),
+  sourceCommit: z.string().regex(/^[0-9a-f]{40,64}$/),
+  contentSha256: z.string().regex(/^[0-9a-f]{64}$/),
+  name: z.string(),
+  status: z.literal("installed"),
+});
+export type InstalledSkill = z.infer<typeof InstalledSkill>;
+
+export const CapabilityComponentOwner = z.object({
+  kind: z.enum(["direct", "plugin", "pack", "migration"]),
+  id: z.string().min(1).max(512),
+  removable: z.boolean(),
+});
+export type CapabilityComponentOwner = z.infer<typeof CapabilityComponentOwner>;
+
+export const SkillUninstallPreview = z.object({
+  capabilityId: z.string().min(1),
+  installed: z.boolean(),
+  installationVersion: z.number().int().positive().nullable(),
+  directOwner: CapabilityComponentOwner.nullable(),
+  remainingOwners: z.array(CapabilityComponentOwner),
+  removesRuntimeSkill: z.boolean(),
+});
+export type SkillUninstallPreview = z.infer<typeof SkillUninstallPreview>;
+
+export const UninstallSkillRequest = z.object({
+  expectedInstallationVersion: z.number().int().positive(),
+});
+export type UninstallSkillRequest = z.infer<typeof UninstallSkillRequest>;
+
+export const UninstallSkillResult = z.object({
+  capabilityId: z.string().min(1),
+  status: z.enum(["not_installed", "uninstalled", "retained_by_other_owners"]),
+  remainingOwners: z.array(CapabilityComponentOwner),
+});
+export type UninstallSkillResult = z.infer<typeof UninstallSkillResult>;
+
+export const ApiIntegrationProtocol = z.enum(["openapi", "graphql"]);
+export type ApiIntegrationProtocol = z.infer<typeof ApiIntegrationProtocol>;
+
+export const IntegrationFeatureKey = z
+  .string()
+  .min(1)
+  .max(200)
+  .regex(/^[a-z0-9](?:[a-z0-9._/-]*[a-z0-9])?$/);
+export type IntegrationFeatureKey = z.infer<typeof IntegrationFeatureKey>;
+
+export const IntegrationFeatureKind = z.enum([
+  "tools",
+  "knowledge_source",
+  "inbound_trigger",
+  "delivery_destination",
+  "identity_link",
+]);
+export type IntegrationFeatureKind = z.infer<typeof IntegrationFeatureKind>;
+
+export const IntegrationFeatureStatus = z.enum(["active", "paused", "needs_attention", "disabled"]);
+export type IntegrationFeatureStatus = z.infer<typeof IntegrationFeatureStatus>;
+
+const IntegrationFeatureJsonObject = z.record(z.string(), z.unknown()).superRefine((value, ctx) => {
+  let serialized: string;
+  try {
+    serialized = JSON.stringify(value);
+  } catch {
+    ctx.addIssue({ code: "custom", message: "must be JSON serializable" });
+    return;
+  }
+  if (new TextEncoder().encode(serialized).byteLength > 131_072) {
+    ctx.addIssue({ code: "custom", message: "must not exceed 131072 UTF-8 bytes" });
+  }
+});
+
+export const IntegrationFeatureDefinitionSummary = z
+  .object({
+    featureKey: IntegrationFeatureKey,
+    kind: IntegrationFeatureKind.exclude(["tools"]),
+    configSchema: IntegrationFeatureJsonObject,
+    capabilities: IntegrationFeatureJsonObject,
+  })
+  .strict();
+export type IntegrationFeatureDefinitionSummary = z.infer<
+  typeof IntegrationFeatureDefinitionSummary
+>;
+
+export const ApiIntegrationPresetSummary = z
+  .object({
+    id: z.string().min(1).max(128),
+    name: z.string().min(1).max(200),
+    summary: z.string().min(1).max(1000),
+    family: z.enum(["google", "microsoft"]),
+    protocol: z.literal("openapi"),
+    providerDomain: z.string().min(1).max(253),
+    scopes: z.array(z.string().min(1).max(1024)).max(256),
+    features: z.array(IntegrationFeatureDefinitionSummary).max(128),
+  })
+  .strict();
+export type ApiIntegrationPresetSummary = z.infer<typeof ApiIntegrationPresetSummary>;
+
+export const ListApiIntegrationPresetsResponse = z
+  .object({ presets: z.array(ApiIntegrationPresetSummary).max(128) })
+  .strict();
+export type ListApiIntegrationPresetsResponse = z.infer<typeof ListApiIntegrationPresetsResponse>;
+
+export const IntegrationInstanceKey = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(/^[a-z0-9](?:[a-z0-9._/-]*[a-z0-9])?$/);
+export type IntegrationInstanceKey = z.infer<typeof IntegrationInstanceKey>;
+
+export const IntegrationFeatureBindingSummary = z
+  .object({
+    id: z.string().uuid(),
+    featureKey: IntegrationFeatureKey,
+    kind: IntegrationFeatureKind.exclude(["tools"]),
+    bindingKey: IntegrationInstanceKey,
+    displayName: z.string().min(1).max(200),
+    connectionId: z.string().uuid().nullable(),
+    status: IntegrationFeatureStatus,
+    config: IntegrationFeatureJsonObject,
+    version: z.number().int().positive(),
+    hasCursor: z.boolean(),
+    lastSuccessAt: z.string().datetime({ offset: true }).nullable(),
+    lastErrorCode: z.string().min(1).max(120).nullable(),
+    createdAt: z.string().datetime({ offset: true }),
+    updatedAt: z.string().datetime({ offset: true }),
+  })
+  .strict();
+export type IntegrationFeatureBindingSummary = z.infer<typeof IntegrationFeatureBindingSummary>;
+
+export const IntegrationInstanceFeaturesResponse = z
+  .object({
+    capabilityId: z.string().min(1).max(512),
+    instanceKey: IntegrationInstanceKey,
+    providerDomain: z.string().min(1).max(253),
+    connectionId: z.string().uuid().nullable(),
+    features: z
+      .array(
+        z
+          .object({
+            definition: IntegrationFeatureDefinitionSummary,
+            binding: IntegrationFeatureBindingSummary.nullable(),
+          })
+          .strict(),
+      )
+      .max(128),
+  })
+  .strict();
+export type IntegrationInstanceFeaturesResponse = z.infer<
+  typeof IntegrationInstanceFeaturesResponse
+>;
+
+export const UpsertIntegrationFeatureRequest = z
+  .object({
+    displayName: z.string().min(1).max(200),
+    config: IntegrationFeatureJsonObject.default({}),
+    expectedVersion: z.number().int().positive().optional(),
+    idempotencyKey: z.string().uuid(),
+  })
+  .strict();
+export type UpsertIntegrationFeatureRequest = z.infer<typeof UpsertIntegrationFeatureRequest>;
+
+export const MutateIntegrationFeatureRequest = z
+  .object({
+    expectedVersion: z.number().int().positive(),
+    idempotencyKey: z.string().uuid(),
+  })
+  .strict();
+export type MutateIntegrationFeatureRequest = z.infer<typeof MutateIntegrationFeatureRequest>;
+
+export const IntegrationFeatureMutationResult = z
+  .object({
+    capabilityId: z.string().min(1).max(512),
+    instanceKey: IntegrationInstanceKey,
+    featureKey: IntegrationFeatureKey,
+    status: z.enum(["configured", "paused", "active"]),
+    binding: IntegrationFeatureBindingSummary,
+  })
+  .strict();
+export type IntegrationFeatureMutationResult = z.infer<typeof IntegrationFeatureMutationResult>;
+
+export const IntegrationFeatureRemovalResult = z
+  .object({
+    capabilityId: z.string().min(1).max(512),
+    instanceKey: IntegrationInstanceKey,
+    featureKey: IntegrationFeatureKey,
+    status: z.enum(["not_configured", "removed", "retained_by_other_owners"]),
+    binding: IntegrationFeatureBindingSummary.nullable(),
+    remainingOwners: z.array(CapabilityComponentOwner),
+  })
+  .strict();
+export type IntegrationFeatureRemovalResult = z.infer<typeof IntegrationFeatureRemovalResult>;
+
+export const ApiIntegrationSource = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("preset"), presetId: z.string().min(1).max(128) }).strict(),
+  z
+    .object({
+      kind: z.literal("openapi"),
+      url: z.string().url().max(2048),
+      baseUrl: z.string().url().max(2048).optional(),
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal("graphql"),
+      endpoint: z.string().url().max(2048),
+      name: z.string().min(1).max(200).optional(),
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal("auto"),
+      url: z.string().url().max(2048),
+      baseUrl: z.string().url().max(2048).optional(),
+    })
+    .strict(),
+]);
+export type ApiIntegrationSource = z.infer<typeof ApiIntegrationSource>;
+
+export const PreviewApiIntegrationRequest = z
+  .object({
+    source: ApiIntegrationSource,
+    connectionId: z.string().uuid().optional(),
+    ownership: ConnectionOwnership.optional(),
+  })
+  .strict();
+export type PreviewApiIntegrationRequest = z.infer<typeof PreviewApiIntegrationRequest>;
+
+export const ApiIntegrationOAuthStartRequest = z
+  .object({
+    presetId: z.string().min(1).max(128),
+    ownership: ConnectionOwnership.optional(),
+    connectionId: z.string().uuid().optional(),
+    returnPath: z.string().min(1).max(2048).optional(),
+  })
+  .strict();
+export type ApiIntegrationOAuthStartRequest = z.infer<typeof ApiIntegrationOAuthStartRequest>;
+
+export const API_INTEGRATION_OAUTH_CREDENTIAL_ROLE = "api_integration_oauth" as const;
+
+export const ApiIntegrationOAuthConnectionMetadata = z
+  .object({
+    credentialRole: z.literal(API_INTEGRATION_OAUTH_CREDENTIAL_ROLE),
+    providerFamily: z.enum(["google", "microsoft"]),
+    providerPrincipalId: z.string().min(1).max(512),
+    providerEmail: z.string().min(1).max(512).nullable(),
+    providerDisplayName: z.string().min(1).max(512).nullable(),
+    authorizedPresetIds: z.array(z.string().min(1).max(128)).min(1).max(32),
+    verifiedAt: z.string().datetime({ offset: true }),
+  })
+  .passthrough();
+export type ApiIntegrationOAuthConnectionMetadata = z.infer<
+  typeof ApiIntegrationOAuthConnectionMetadata
+>;
+
+export const ApiIntegrationAuthPreview = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("none") }).strict(),
+  z
+    .object({
+      kind: z.literal("oauth2"),
+      providerDomain: z.string().min(1).max(253),
+      scopes: z.array(z.string().min(1).max(1024)).max(256),
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal("api_key"),
+      providerDomain: z.string().min(1).max(253),
+      carrier: z.enum(["header", "query", "cookie"]),
+      name: z.string().min(1).max(256),
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal("http"),
+      providerDomain: z.string().min(1).max(253),
+      scheme: z.string().min(1).max(64),
+    })
+    .strict(),
+]);
+export type ApiIntegrationAuthPreview = z.infer<typeof ApiIntegrationAuthPreview>;
+
+export const ApiIntegrationToolPreview = z
+  .object({
+    id: z.string().min(1).max(200),
+    operationKey: z.string().min(1).max(512),
+    name: z.string().min(1).max(200),
+    description: z.string().max(4000),
+    safety: z.enum(["read", "write", "destructive"]),
+    approvalMode: z.enum(["never", "ask"]),
+    deprecated: z.boolean(),
+  })
+  .strict();
+export type ApiIntegrationToolPreview = z.infer<typeof ApiIntegrationToolPreview>;
+
+export const ApiIntegrationPreview = z
+  .object({
+    source: ApiIntegrationSource,
+    presetId: z.string().min(1).max(128).nullable(),
+    protocol: ApiIntegrationProtocol,
+    integrationId: z.string().min(1).max(200),
+    capabilityId: z.string().min(1).max(512),
+    pluginKey: z.string().min(1).max(200),
+    serverId: SessionMcpServerId,
+    name: z.string().min(1).max(200),
+    description: z.string().max(4000).nullable(),
+    provider: z.string().min(1).max(128).nullable(),
+    providerDomain: z.string().min(1).max(253),
+    baseUrl: z.string().url().max(2048),
+    sourceUrl: z.string().url().max(2048).nullable(),
+    revisionId: z.string().min(1).max(96),
+    contentSha256: z.string().regex(/^[0-9a-f]{64}$/),
+    auth: ApiIntegrationAuthPreview,
+    connectionId: z.string().uuid().nullable(),
+    connectionOwnership: ConnectionOwnership.nullable(),
+    tools: z.array(ApiIntegrationToolPreview).min(1).max(2000),
+    warnings: z.array(z.string().min(1).max(500)).max(32).default([]),
+  })
+  .strict();
+export type ApiIntegrationPreview = z.infer<typeof ApiIntegrationPreview>;
+
+export const InstallApiIntegrationRequest = z
+  .object({
+    source: ApiIntegrationSource,
+    expectedRevisionId: z.string().min(1).max(96),
+    expectedContentSha256: z.string().regex(/^[0-9a-f]{64}$/),
+    connectionId: z.string().uuid().optional(),
+    ownership: ConnectionOwnership.optional(),
+    instanceKey: IntegrationInstanceKey.optional(),
+    displayName: z.string().min(1).max(200).optional(),
+    expectedInstanceVersion: z.number().int().positive().optional(),
+    allowedTools: z.array(z.string().min(1).max(200)).max(2000).optional(),
+  })
+  .strict();
+export type InstallApiIntegrationRequest = z.infer<typeof InstallApiIntegrationRequest>;
+
+export const InstalledApiIntegration = z
+  .object({
+    capabilityId: z.string().min(1),
+    pluginId: z.string().uuid(),
+    pluginVersionId: z.string().uuid(),
+    integrationFacetId: z.string().uuid(),
+    apiFacetId: z.string().uuid(),
+    pluginInstallationId: z.string().uuid(),
+    integrationFacetInstallationId: z.string().uuid(),
+    apiFacetInstallationId: z.string().uuid(),
+    installationVersion: z.number().int().positive(),
+    instanceId: z.string().uuid(),
+    instanceKey: IntegrationInstanceKey,
+    displayName: z.string().min(1).max(200),
+    instanceVersion: z.number().int().positive(),
+    revisionId: z.string().min(1),
+    serverId: SessionMcpServerId,
+    status: z.literal("installed"),
+  })
+  .strict();
+export type InstalledApiIntegration = z.infer<typeof InstalledApiIntegration>;
+
+export const ApiIntegrationInstallationSummary = z
+  .object({
+    capabilityId: z.string().min(1),
+    pluginKey: z.string().min(1),
+    installationVersion: z.number().int().positive(),
+    instanceId: z.string().uuid(),
+    instanceKey: IntegrationInstanceKey,
+    displayName: z.string().min(1).max(200),
+    instanceVersion: z.number().int().positive(),
+    serverId: SessionMcpServerId,
+    name: z.string().min(1),
+    description: z.string().nullable(),
+    protocol: ApiIntegrationProtocol,
+    presetId: z.string().min(1).max(128).nullable(),
+    providerDomain: z.string().min(1),
+    baseUrl: z.string().url(),
+    sourceUrl: z.string().url().nullable(),
+    connected: z.boolean(),
+    requiresConnection: z.boolean(),
+    connectionId: z.string().uuid().nullable(),
+    ownership: z.enum(["workspace", "personal", "none"]),
+    allowedTools: z.array(z.string().min(1).max(200)).max(2000),
+    toolCount: z.number().int().nonnegative(),
+    approvalRequiredToolCount: z.number().int().nonnegative(),
+    revisionId: z.string().min(1),
+    contentSha256: z.string().regex(/^[0-9a-f]{64}$/),
+  })
+  .strict();
+export type ApiIntegrationInstallationSummary = z.infer<typeof ApiIntegrationInstallationSummary>;
+
+export const ListApiIntegrationsResponse = z
+  .object({ integrations: z.array(ApiIntegrationInstallationSummary) })
+  .strict();
+export type ListApiIntegrationsResponse = z.infer<typeof ListApiIntegrationsResponse>;
+
+export const ApiIntegrationUninstallPreview = z
+  .object({
+    capabilityId: z.string().min(1),
+    instanceKey: IntegrationInstanceKey,
+    displayName: z.string().min(1).max(200).nullable(),
+    installed: z.boolean(),
+    installationVersion: z.number().int().positive().nullable(),
+    instanceVersion: z.number().int().positive().nullable(),
+    directOwner: CapabilityComponentOwner.nullable(),
+    remainingOwners: z.array(CapabilityComponentOwner),
+    removesRuntimeIntegration: z.boolean(),
+    removesDefinition: z.boolean(),
+  })
+  .strict();
+export type ApiIntegrationUninstallPreview = z.infer<typeof ApiIntegrationUninstallPreview>;
+
+export const UninstallApiIntegrationRequest = z
+  .object({
+    expectedInstallationVersion: z.number().int().positive(),
+    expectedInstanceVersion: z.number().int().positive(),
+  })
+  .strict();
+export type UninstallApiIntegrationRequest = z.infer<typeof UninstallApiIntegrationRequest>;
+
+export const UninstallApiIntegrationResult = z
+  .object({
+    capabilityId: z.string().min(1),
+    instanceKey: IntegrationInstanceKey,
+    status: z.enum(["not_installed", "uninstalled", "retained_by_other_owners"]),
+    remainingOwners: z.array(CapabilityComponentOwner),
+    definitionStatus: z.enum(["retained", "disabled"]),
+  })
+  .strict();
+export type UninstallApiIntegrationResult = z.infer<typeof UninstallApiIntegrationResult>;
+
+const PluginComponentKey = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(/^[a-z0-9](?:[a-z0-9._/-]*[a-z0-9])?$/);
+
+export const PluginManifest = z
+  .object({
+    schemaVersion: z.literal(1),
+    pluginKey: z
+      .string()
+      .min(1)
+      .max(200)
+      .regex(/^[a-z0-9](?:[a-z0-9._/-]*[a-z0-9])?$/),
+    version: z.string().min(1).max(128),
+    name: z.string().min(1).max(200),
+    description: z.string().max(4000).default(""),
+    category: z.string().min(1).max(100).default("plugins"),
+    tags: z.array(z.string().min(1).max(100)).max(64).default([]),
+    components: z
+      .array(
+        z.discriminatedUnion("kind", [
+          z
+            .object({ key: PluginComponentKey, kind: z.literal("skill"), url: z.string().url() })
+            .strict(),
+          z
+            .object({
+              key: PluginComponentKey,
+              kind: z.literal("integration"),
+              source: ApiIntegrationSource,
+            })
+            .strict(),
+          z
+            .object({
+              key: PluginComponentKey,
+              kind: z.literal("mcp"),
+              serverId: SessionMcpServerId,
+            })
+            .strict(),
+        ]),
+      )
+      .min(1)
+      .max(64),
+  })
+  .strict()
+  .superRefine((manifest, context) => {
+    const seen = new Set<string>();
+    for (const [index, component] of manifest.components.entries()) {
+      if (seen.has(component.key)) {
+        context.addIssue({
+          code: "custom",
+          message: "Plugin component keys must be unique",
+          path: ["components", index, "key"],
+        });
+      }
+      seen.add(component.key);
+    }
+  });
+export type PluginManifest = z.infer<typeof PluginManifest>;
+
+export const PluginComponentBinding = z
+  .object({
+    connectionId: z.string().uuid().optional(),
+    instanceKey: IntegrationInstanceKey.optional(),
+    displayName: z.string().min(1).max(200).optional(),
+  })
+  .strict();
+export type PluginComponentBinding = z.infer<typeof PluginComponentBinding>;
+
+export const PreviewPluginRequest = z
+  .object({
+    url: z.string().url().max(2048),
+    bindings: z.record(PluginComponentKey, PluginComponentBinding).default({}),
+  })
+  .strict();
+export type PreviewPluginRequest = z.infer<typeof PreviewPluginRequest>;
 
-export const CapabilityCatalogAuthKind = z.enum(["oauth2", "api_key", "none", "unknown"]);
-export type CapabilityCatalogAuthKind = z.infer<typeof CapabilityCatalogAuthKind>;
+export const PluginComponentPreview = z
+  .object({
+    key: PluginComponentKey,
+    kind: z.enum(["skill", "integration", "mcp"]),
+    name: z.string().min(1).max(200),
+    capabilityId: z.string().min(1).max(512),
+    digest: z.string().regex(/^[0-9a-f]{64}$/),
+    connectionRequired: z.boolean(),
+    connectionId: z.string().uuid().nullable(),
+    instanceKey: IntegrationInstanceKey.nullable(),
+    displayName: z.string().min(1).max(200).nullable(),
+    facts: z.record(z.string(), z.unknown()),
+  })
+  .strict();
+export type PluginComponentPreview = z.infer<typeof PluginComponentPreview>;
 
-export const CapabilityCatalogTier = z.enum(["verified", "community"]);
-export type CapabilityCatalogTier = z.infer<typeof CapabilityCatalogTier>;
+export const PluginUpdateDiff = z
+  .object({
+    fromVersion: z.string().nullable(),
+    toVersion: z.string().min(1),
+    added: z.array(PluginComponentKey),
+    removed: z.array(PluginComponentKey),
+    changed: z.array(PluginComponentKey),
+    unchanged: z.array(PluginComponentKey),
+  })
+  .strict();
+export type PluginUpdateDiff = z.infer<typeof PluginUpdateDiff>;
 
-export const CapabilityRuntime = z.object({
-  available: z.boolean().default(false),
-  mcpServerId: z.string().min(1).optional(),
-  transport: z.string().min(1).optional(),
-  notes: z.string().nullable().default(null),
-  // Registry exposure provenance is server-derived and contains no endpoint or
-  // credential material.
-  catalogTrust: z
-    .object({
-      state: z.enum(["trusted", "legacy_active", "unverified"]),
-      reason: z.enum([
-        "trusted_source",
-        "verified_probe",
-        "active_installation_compatibility",
-        "missing_verification",
-      ]),
-    })
-    .optional(),
-});
-export type CapabilityRuntime = z.infer<typeof CapabilityRuntime>;
+export const PluginPreview = z
+  .object({
+    sourceUrl: z.string().url(),
+    manifest: PluginManifest,
+    manifestDigest: z.string().regex(/^[0-9a-f]{64}$/),
+    installed: z.boolean(),
+    installationVersion: z.number().int().positive().nullable(),
+    components: z.array(PluginComponentPreview).min(1).max(64),
+    diff: PluginUpdateDiff,
+  })
+  .strict();
+export type PluginPreview = z.infer<typeof PluginPreview>;
 
-export const CapabilityCatalogItem = z.object({
-  id: z.string().min(1),
-  accountId: z.string().uuid().optional(),
-  workspaceId: z.string().uuid().optional(),
-  kind: CapabilityKind,
-  source: CapabilitySource,
-  name: z.string().min(1),
-  description: z.string().nullable().default(null),
-  category: z.string().min(1).default("custom"),
-  tags: z.array(z.string().min(1)).default([]),
-  homepageUrl: z.string().url().nullable().default(null),
-  endpointUrl: z.string().url().nullable().default(null),
-  installUrl: z.string().url().nullable().default(null),
-  authModel: z.string().min(1).nullable().default(null),
-  providerDomain: z.string().min(1).nullable().default(null),
-  surfaceType: z.string().min(1).nullable().default(null),
-  transport: z.string().min(1).nullable().default(null),
-  mcpUrl: z.string().url().nullable().default(null),
-  authKind: CapabilityCatalogAuthKind.nullable().default(null),
-  credentialFacts: z.array(z.record(z.string(), z.unknown())).default([]),
-  tier: CapabilityCatalogTier.nullable().default(null),
-  provenance: z.string().min(1).nullable().default(null),
-  logoAssetPath: z.string().min(1).nullable().default(null),
-  importBatchId: z.string().uuid().nullable().default(null),
-  stale: z.boolean().default(false),
-  staleAt: z.string().nullable().default(null),
-  tools: z.array(ToolRef).default([]),
-  runtime: CapabilityRuntime.default({ available: false, notes: null }),
-  enabled: z.boolean().default(false),
-  enabledReason: z.string().nullable().default(null),
-  // The non-secret connection binding stored with an enabled installation.
-  // Workspace refs retain an exact row id. Subject refs deliberately omit it:
-  // each caller resolves their own visible row by provider/kind at runtime.
-  connectionRef: z
-    .object({
-      connectionId: z.string().min(1).optional(),
-      providerDomain: z.string().min(1),
-      kind: z.string().min(1),
-      subjectScope: z.enum(["workspace", "subject"]).optional(),
-    })
-    .nullable()
-    .default(null),
-  metadata: z.record(z.string(), z.unknown()).default({}),
-  createdAt: z.string().optional(),
-  updatedAt: z.string().optional(),
-});
-export type CapabilityCatalogItem = z.infer<typeof CapabilityCatalogItem>;
+export const InstallPluginRequest = z
+  .object({
+    url: z.string().url().max(2048),
+    expectedManifestDigest: z.string().regex(/^[0-9a-f]{64}$/),
+    expectedComponents: z
+      .array(
+        z.object({ key: PluginComponentKey, digest: z.string().regex(/^[0-9a-f]{64}$/) }).strict(),
+      )
+      .min(1)
+      .max(64),
+    bindings: z.record(PluginComponentKey, PluginComponentBinding).default({}),
+    idempotencyKey: z.string().uuid(),
+    expectedInstallationVersion: z.number().int().positive().optional(),
+  })
+  .strict();
+export type InstallPluginRequest = z.infer<typeof InstallPluginRequest>;
 
-/**
- * Shared trust gate for catalog visibility and runtime selection. Registry rows
- * remain durable for provenance and audit, but only a reviewed real-MCP probe
- * with known authentication is exposable. API-key rows additionally need a
- * machine-actionable header contract; prose credential instructions are not a
- * runtime contract and must fail closed.
- */
-export function capabilityCatalogItemIsTrustedForExposure(
-  item: Pick<CapabilityCatalogItem, "source" | "stale" | "authKind" | "metadata">,
-): boolean {
-  if (item.stale) return false;
-  if (item.source !== "registry") return true;
-  const probe = item.metadata.mcpProbe;
-  if (!probe || typeof probe !== "object" || Array.isArray(probe)) return false;
-  if ((probe as Record<string, unknown>).status !== "real") return false;
-  if (item.authKind === null || item.authKind === "unknown") return false;
-  if (item.authKind !== "api_key") return true;
-  const contract = item.metadata.authContract;
-  if (!contract || typeof contract !== "object" || Array.isArray(contract)) return false;
-  const record = contract as Record<string, unknown>;
-  return (
-    typeof record.headerName === "string" &&
-    /^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/.test(record.headerName) &&
-    typeof record.scheme === "string" &&
-    record.scheme.trim().length > 0
-  );
-}
+export const InstalledPlugin = z
+  .object({
+    pluginKey: z.string().min(1),
+    version: z.string().min(1),
+    pluginId: z.string().uuid(),
+    pluginVersionId: z.string().uuid(),
+    pluginInstallationId: z.string().uuid(),
+    installationVersion: z.number().int().positive(),
+    componentCount: z.number().int().positive(),
+    status: z.literal("installed"),
+  })
+  .strict();
+export type InstalledPlugin = z.infer<typeof InstalledPlugin>;
 
-export const CapabilityInstallation = z.object({
-  id: z.string().uuid(),
-  accountId: z.string().uuid(),
-  workspaceId: z.string().uuid(),
-  capabilityId: z.string().min(1),
-  kind: CapabilityKind,
-  status: CapabilityInstallationStatus,
-  config: z.record(z.string(), z.unknown()),
-  metadata: z.record(z.string(), z.unknown()),
-  enabledAt: z.string(),
-  updatedAt: z.string(),
-});
-export type CapabilityInstallation = z.infer<typeof CapabilityInstallation>;
+export const PluginInstallationSummary = z
+  .object({
+    pluginKey: z.string().min(1).max(200),
+    version: z.string().min(1).max(128),
+    name: z.string().min(1).max(200),
+    description: z.string().max(4000),
+    category: z.string().min(1).max(100),
+    tags: z.array(z.string().min(1).max(100)).max(64),
+    sourceUrl: z.string().url().max(2048).nullable(),
+    manifestDigest: z.string().regex(/^[0-9a-f]{64}$/),
+    installationVersion: z.number().int().positive(),
+    componentCount: z.number().int().nonnegative().max(64),
+    status: z.enum(["active", "needs_attention"]),
+    installedAt: z.string().datetime({ offset: true }),
+    updatedAt: z.string().datetime({ offset: true }),
+  })
+  .strict();
+export type PluginInstallationSummary = z.infer<typeof PluginInstallationSummary>;
 
-export const CreateCapabilityCatalogItemRequest = z.object({
-  id: z.string().min(1).optional(),
-  kind: CapabilityKind.exclude(["pack"]),
-  source: CapabilitySource.default("manual"),
-  name: z.string().min(1),
-  description: z.string().min(1).optional(),
-  category: z.string().min(1).default("custom"),
-  tags: z.array(z.string().min(1)).default([]),
-  homepageUrl: z.string().url().optional(),
-  endpointUrl: z.string().url().optional(),
-  installUrl: z.string().url().optional(),
-  authModel: z.string().min(1).optional(),
-  metadata: z.record(z.string(), z.unknown()).default({}),
-});
-export type CreateCapabilityCatalogItemRequest = z.infer<typeof CreateCapabilityCatalogItemRequest>;
+export const ListInstalledPluginsResponse = z
+  .object({ plugins: z.array(PluginInstallationSummary).max(1000) })
+  .strict();
+export type ListInstalledPluginsResponse = z.infer<typeof ListInstalledPluginsResponse>;
 
-export const EnableCapabilityRequest = withVariableSetIdAlias({
-  config: z.record(z.string(), z.unknown()).default({}),
-  metadata: z.record(z.string(), z.unknown()).default({}),
-  connectionRef: McpServerConnectionRef.optional(),
-  /**
-   * Credential headers for remote MCP capabilities (for example an
-   * Authorization bearer token). Values are encrypted at rest with the
-   * workspace-variable-sets key, injected only into the runtime MCP client,
-   * and never returned by the API — responses expose header names only.
-   */
-  headers: z.record(z.string(), z.string()).default({}),
-  /**
-   * Initial variableSet attachment for kind=pack capabilities. Mirrors the
-   * dedicated POST /packs/:id/enable body: required to enable an
-   * variableSet.required pack through the unified capability-enable path,
-   * optional otherwise. Ignored by non-pack capabilities.
-   */
-  variableSetId: z.string().uuid().optional(),
-  environmentId: z.string().uuid().optional(),
-});
-export type EnableCapabilityRequest = z.infer<typeof EnableCapabilityRequest>;
+export const PluginUninstallPreview = z
+  .object({
+    pluginKey: z.string().min(1),
+    installed: z.boolean(),
+    version: z.string().nullable(),
+    installationVersion: z.number().int().positive().nullable(),
+    components: z.array(
+      z.object({
+        capabilityId: z.string().min(1),
+        kind: z.enum(["skill", "integration", "mcp"]),
+        retainedByOtherOwners: z.boolean(),
+      }),
+    ),
+  })
+  .strict();
+export type PluginUninstallPreview = z.infer<typeof PluginUninstallPreview>;
 
-export const CapabilityCatalogResponse = z.object({
-  items: z.array(CapabilityCatalogItem),
-  installations: z.array(CapabilityInstallation),
-});
-export type CapabilityCatalogResponse = z.infer<typeof CapabilityCatalogResponse>;
+export const UninstallPluginRequest = z
+  .object({
+    expectedInstallationVersion: z.number().int().positive(),
+    idempotencyKey: z.string().uuid(),
+  })
+  .strict();
+export type UninstallPluginRequest = z.infer<typeof UninstallPluginRequest>;
 
-export const DiscoverMcpCapabilitiesResponse = z.object({
-  items: z.array(CapabilityCatalogItem),
-  source: z.literal("official_mcp_registry"),
-  sourceUrl: z.string().url(),
-});
-export type DiscoverMcpCapabilitiesResponse = z.infer<typeof DiscoverMcpCapabilitiesResponse>;
+export const UninstallPluginResult = z
+  .object({
+    pluginKey: z.string().min(1),
+    status: z.enum(["not_installed", "uninstalled"]),
+    retainedComponents: z.array(z.string().min(1)),
+  })
+  .strict();
+export type UninstallPluginResult = z.infer<typeof UninstallPluginResult>;
 
 export const Session = z.object({
   id: z.string().uuid(),
@@ -6535,6 +8412,57 @@ export const SessionListResponse = z.object({
 });
 export type SessionListResponse = z.infer<typeof SessionListResponse>;
 
+/** Compact, bounded session projection for workspace agent-topology browsers. */
+export const AgentTopologySession = z.object({
+  id: z.string().uuid(),
+  title: z.string().nullable(),
+  titleTruncated: z.boolean(),
+  parentSessionId: z.string().uuid().nullable(),
+  rootSessionId: z.string().uuid(),
+  nestedAgentDepth: NestedAgentDepthValue,
+  ancestorPath: z.array(
+    z.object({
+      id: z.string().uuid(),
+      title: z.string().nullable(),
+      titleTruncated: z.boolean(),
+    }),
+  ),
+  status: SessionStatus,
+  pause: z.object({
+    state: z.enum(["active", "paused"]),
+    additionalBlockerCount: z.number().int().nonnegative(),
+    source: z
+      .object({
+        kind: z.enum(["session", "workspace"]),
+        sessionId: z.string().uuid().optional(),
+        displayName: z.string(),
+        displayNameTruncated: z.boolean(),
+      })
+      .nullable(),
+  }),
+  children: z.object({
+    directChildren: z.number().int().nonnegative(),
+    totalDescendants: z.number().int().nonnegative(),
+    runningDescendants: z.number().int().nonnegative(),
+    queuedDescendants: z.number().int().nonnegative(),
+    attentionDescendants: z.number().int().nonnegative(),
+    pausedDescendants: z.number().int().nonnegative(),
+    failedDescendants: z.number().int().nonnegative(),
+    truncated: z.boolean(),
+  }),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type AgentTopologySession = z.infer<typeof AgentTopologySession>;
+
+export const AgentTopologyPageResponse = z.object({
+  sessions: z.array(AgentTopologySession),
+  total: z.number().int().nonnegative(),
+  hasMore: z.boolean(),
+  nextCursor: z.string().nullable(),
+});
+export type AgentTopologyPageResponse = z.infer<typeof AgentTopologyPageResponse>;
+
 // Recursive: the TS type is declared first so the schema annotation can carry
 // the FULL recursive shape (a shallow annotation loses type information for
 // contracts consumers after one level of nesting).
@@ -6953,6 +8881,21 @@ export const ToolAuthNeededPayload = z.object({
   selectedResources: McpConnectionResourceScopes.optional(),
   authorizationUrl: z.string().url().optional(),
   subjectId: z.string().min(1).nullable().optional(),
+  // A catalog recommendation is still a tool-level authorization condition:
+  // the agent may describe and request it, but only the authenticated host UI
+  // can start setup. Keeping this nested and optional preserves the established
+  // auth-needed event for ordinary failed MCP calls.
+  capability: z
+    .object({
+      id: z.string().min(1).max(512),
+      name: z.string().min(1).max(256),
+      kind: CapabilityKind,
+      source: CapabilitySource,
+      action: z.enum(["connect", "add_credentials", "enable"]),
+      rationale: z.string().min(1).max(2000),
+      requiredVariables: z.array(VariableSetVariableName).max(64).default([]),
+    })
+    .optional(),
 });
 export type ToolAuthNeededPayload = z.infer<typeof ToolAuthNeededPayload>;
 
@@ -7307,6 +9250,9 @@ export type GitStatusRequest = z.infer<typeof GitStatusRequest>;
 export const GitStatusResponse = z.object({
   isRepo: z.boolean(),
   head: z.string().nullable(), // branch name
+  // Exact commit object identity. null for unborn/non-repositories; optional
+  // only so older adapters and serialized captures remain readable.
+  headOid: z.string().nullable().optional(),
   detached: z.boolean().default(false),
   upstream: z.string().nullable(),
   ahead: z.number().int().nonnegative().default(0),
@@ -7432,6 +9378,9 @@ export type WorkspaceCaptureFile = z.infer<typeof WorkspaceCaptureFile>;
 export const WorkspaceCaptureRepo = z.object({
   root: z.string(),
   head: z.string().nullable(),
+  // Exact HEAD commit object identity. null for unborn repositories; optional
+  // for workspace captures written before commit identity was retained.
+  headOid: z.string().nullable().optional(),
   detached: z.boolean().default(false),
   upstream: z.string().nullable(),
   ahead: z.number().int().nonnegative().default(0),
@@ -9003,27 +10952,45 @@ export function approvalIdentifier(value: unknown): string | null {
   return String(candidate);
 }
 
+function requireMessageTextOrAnnotations(
+  value: { text: string; annotations: readonly unknown[] },
+  ctx: z.RefinementCtx,
+): void {
+  if (value.text.length === 0 && value.annotations.length === 0) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["text"],
+      message: "message text or annotations are required",
+    });
+  }
+}
+
+export const SessionUserMessagePayload = z
+  .object({
+    text: z.string().default(""),
+    annotations: SubmittedTimelineAnnotations.default([]),
+    // System-level host context for this exact turn only. Persisted on the
+    // turn for retry/recovery, never copied into the visible user message.
+    turnInstructions: z.string().trim().min(1).max(32768).optional(),
+    resources: z.array(ResourceRef).default([]),
+    model: z.string().min(1).optional(),
+    reasoningEffort: ReasoningEffort.optional(),
+    latencyMode: LatencyMode.optional(),
+    controlEtag: z.string().min(1).optional(),
+    expectedDraftRevision: z.number().int().nonnegative().optional(),
+    // Header-value rotation only. URL/name/tool settings are immutable after
+    // session create; persisted events expose metadata, never header values.
+    mcpCredentialUpdates: z.array(SessionMcpCredentialUpdateInput).optional(),
+  })
+  .strict()
+  .superRefine(requireMessageTextOrAnnotations);
+export type SessionUserMessagePayload = z.infer<typeof SessionUserMessagePayload>;
+
 export const ClientSessionEvent = z.discriminatedUnion("type", [
   z.object({
     type: z.literal("user.message"),
     clientEventId: SessionOperationKey.optional(),
-    payload: z
-      .object({
-        text: z.string().min(1),
-        // System-level host context for this exact turn only. Persisted on the
-        // turn for retry/recovery, never copied into the visible user message.
-        turnInstructions: z.string().trim().min(1).max(32768).optional(),
-        resources: z.array(ResourceRef).default([]),
-        model: z.string().min(1).optional(),
-        reasoningEffort: ReasoningEffort.optional(),
-        latencyMode: LatencyMode.optional(),
-        controlEtag: z.string().min(1).optional(),
-        expectedDraftRevision: z.number().int().nonnegative().optional(),
-        // Header-value rotation only. URL/name/tool settings are immutable after
-        // session create; persisted events expose metadata, never header values.
-        mcpCredentialUpdates: z.array(SessionMcpCredentialUpdateInput).optional(),
-      })
-      .strict(),
+    payload: SessionUserMessagePayload,
   }),
   z.object({
     type: z.literal("user.approvalDecision"),
@@ -9047,7 +11014,8 @@ export type ClientSessionEvent = z.infer<typeof ClientSessionEvent>;
 
 export const SteerSessionMessageRequest = z
   .object({
-    text: z.string().min(1),
+    text: z.string().default(""),
+    annotations: SubmittedTimelineAnnotations.default([]),
     // Same per-turn system-level context as a queued user.message.
     turnInstructions: z.string().trim().min(1).max(32768).optional(),
     resources: z.array(ResourceRef).default([]),
@@ -9059,7 +11027,8 @@ export const SteerSessionMessageRequest = z
     expectedDraftRevision: z.number().int().nonnegative().optional(),
     mcpCredentialUpdates: z.array(SessionMcpCredentialUpdateInput).optional(),
   })
-  .strict();
+  .strict()
+  .superRefine(requireMessageTextOrAnnotations);
 export type SteerSessionMessageRequest = z.infer<typeof SteerSessionMessageRequest>;
 
 export const SteerSessionMessageResponse = z.object({
@@ -9278,19 +11247,21 @@ export type SessionCapabilities = z.infer<typeof SessionCapabilities>;
 // POST .../viewers — acquire a viewer holder. An omitted viewerId mints a fresh
 // one (returned in the response, to carry through heartbeats + detach).
 //
-// `desktop` declares intent to attach the UN-REDACTED pixel plane (noVNC). ONLY
-// that plane carries the consent gate (the un-redacted/shared acknowledgment). A
-// terminal-only warm attach (`desktop:false`, the default) needs NO consent — a
-// shell is interactive by nature and the gate is the scoped tunnel URL + stream
-// token — so it warms the box and mints the pty-ws terminal cell WITHOUT a 409.
-// Omitted defaults to `false` so a terminal-only client never trips the gate.
-export const AttachViewerRequest = z.object({
+// Each optional plane flag declares exactly which live capability is being
+// acquired. The holder itself is shared liveness; credentials are minted only
+// for explicitly requested planes. `desktop` alone carries the un-redacted pixel
+// consent gate, `terminal` carries terminal:attach, and `files` carries
+// files:write. For compatibility, an entirely omitted plane set retains the old
+// terminal-only meaning; new clients always send all three flags explicitly.
+export const AttachViewerRequest = /* @__PURE__ */ z.object({
   viewerId: z.string().uuid().optional(),
   desktop: z.boolean().optional(),
+  terminal: z.boolean().optional(),
+  files: z.boolean().optional(),
 });
 export type AttachViewerRequest = z.infer<typeof AttachViewerRequest>;
 
-export const ViewerHolder = z.object({
+export const ViewerHolder = /* @__PURE__ */ z.object({
   viewerId: z.string().uuid(),
   sandboxGroupId: z.string().uuid(),
   liveness: z.enum(["cold", "warming", "warm", "draining"]),
@@ -9306,6 +11277,21 @@ export const ViewerHolder = z.object({
 });
 export type ViewerHolder = z.infer<typeof ViewerHolder>;
 
+/** Exact POST /viewers response. Keep the credential cells in the contracts
+ * package so API and zero-runtime SDK mirrors cannot silently drift. */
+export const AttachViewerResponse = /* @__PURE__ */ ViewerHolder.extend({
+  streamToken: z.string().nullable(),
+  streamExpiresAt: z.string().nullable(),
+  resolution: z.tuple([z.number().int().positive(), z.number().int().positive()]).nullable(),
+  transport: z.enum(["vnc-ws", "relay-frames"]).nullable(),
+  client: z.enum(["novnc", "frames"]).nullable(),
+  terminalUrl: z.string().nullable(),
+  terminalToken: z.string().nullable(),
+  terminalExpiresAt: z.string().nullable(),
+  terminalTransport: z.literal("pty-ws").nullable(),
+});
+export type AttachViewerResponse = z.infer<typeof AttachViewerResponse>;
+
 // POST .../stream-capabilities/acknowledge — record the calling principal's
 // acknowledgment of the un-redacted pixel plane. Reuses the acknowledgment
 // machinery — no new endpoint
@@ -9315,7 +11301,7 @@ export type ViewerHolder = z.infer<typeof ViewerHolder>;
 // session): the un-redacted desktop path returns 409 shared_acknowledgment_required
 // until a shared box is acknowledged WITH the shared-exposure consent. For a
 // solo box `acknowledgeShared` is irrelevant (the un-redacted ack alone gates).
-export const AcknowledgeStreamRequest = z.object({
+export const AcknowledgeStreamRequest = /* @__PURE__ */ z.object({
   // The principal accepts that the desktop pixel plane is un-redacted (can show
   // cloud creds the agent cat's into a terminal). Always true to record consent;
   // present for self-documentation + a future explicit withdraw.
@@ -9326,7 +11312,7 @@ export const AcknowledgeStreamRequest = z.object({
 });
 export type AcknowledgeStreamRequest = z.infer<typeof AcknowledgeStreamRequest>;
 
-export const AcknowledgeStreamResponse = z.object({
+export const AcknowledgeStreamResponse = /* @__PURE__ */ z.object({
   acknowledged: z.boolean(),
   acknowledgedShared: z.boolean(),
 });
@@ -9334,12 +11320,12 @@ export type AcknowledgeStreamResponse = z.infer<typeof AcknowledgeStreamResponse
 
 // POST .../viewers/:viewerId/heartbeat — refresh the holder TTL. Epoch-fenced:
 // a stale-epoch beat (a box re-established under a newer epoch) is rejected.
-export const ViewerHeartbeatRequest = z.object({
+export const ViewerHeartbeatRequest = /* @__PURE__ */ z.object({
   leaseEpoch: z.number().int().nonnegative(),
 });
 export type ViewerHeartbeatRequest = z.infer<typeof ViewerHeartbeatRequest>;
 
-export const ViewerHeartbeatResponse = z.object({
+export const ViewerHeartbeatResponse = /* @__PURE__ */ z.object({
   // false ⇒ the holder was reaped or the epoch is stale; the client re-attaches.
   alive: z.boolean(),
 });
@@ -9508,10 +11494,23 @@ export const RevokeEnrollmentResponse = z.object({
   lastSeenAt: z.string().datetime({ offset: true }).nullable(),
   revokedAt: z.string().datetime({ offset: true }).nullable(),
   code: z
-    .enum(["active_route", "active_commands", "active_lease", "recovery_pending", "not_selfhosted"])
+    .enum([
+      "active_route",
+      "active_commands",
+      "machine_home",
+      "active_lease",
+      "recovery_pending",
+      "not_selfhosted",
+    ])
     .nullable(),
   message: z.string(),
   action: z.string(),
+  dependentSessions: z.array(
+    z.object({
+      id: z.string().uuid(),
+      title: z.string().nullable(),
+    }),
+  ),
 });
 export type RevokeEnrollmentResponse = z.infer<typeof RevokeEnrollmentResponse>;
 
@@ -10173,7 +12172,7 @@ export type WorkspaceModelCatalogResponse = z.infer<typeof WorkspaceModelCatalog
  * that rollout boundary. Mutating clients send this value in
  * `x-opengeni-api-contract`; the API rejects any other value before routing.
  */
-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;
@@ -10336,6 +12335,8 @@ export function evaluateWorkspaceModelPolicy(
 
 export * from "./codex-fleet-policy";
 export * from "./workspace-instruction-policies";
+export * from "./company-profile";
+export * from "./workspace-learning-policy";
 export * from "./workspace-state";
 export * from "./preference-registry";
 export * from "./scoped-knowledge";