@opengeni/contracts 0.7.0 → 0.10.0

package/dist/index.js

@@ -5,6 +5,9 @@ var SessionStatus = z.enum([
   "running",
   "idle",
   "requires_action",
+  "recovering",
+  "waiting_capacity",
+  "paused",
   "failed",
   "cancelled"
 ]);
@@ -412,12 +415,22 @@ var Permission = z.enum([
   "github:manage",
   "github:use",
   "api_keys:manage",
+  "connections:read",
+  "connections:write",
+  /** @deprecated alias of variable-sets:manage */
   "environments:manage",
+  /** @deprecated alias of variable-sets:use */
   "environments:use",
+  "variable-sets:manage",
+  "variable-sets:use",
   // Attach or rotate per-session third-party MCP server credentials. Deliberately
   // not part of the worker's default first-party MCP permission set: a sandboxed
   // agent must not be able to hand itself new bearer credentials.
   "mcp_servers:attach",
+  // 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",
   "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
@@ -425,8 +438,18 @@ var Permission = z.enum([
   // enrollment grants WHOLE-MACHINE access to a user's own hardware — a high-trust,
   // admin-shaped action. workspace:admin is the super-wildcard over both.
   "enrollments:read",
-  "enrollments:manage"
+  "enrollments:manage",
+  // Rigs (workspace-scoped, versioned sandbox machine definitions). rigs:use is
+  // read + propose-change (the agent-native, additive path a sandboxed session
+  // is trusted with); rigs:manage is create/edit/activate/promote/delete (the
+  // admin-shaped path that mints or rolls versions). workspace:admin is the
+  // super-wildcard over both.
+  "rigs:use",
+  "rigs:manage"
 ]);
+function prefixedMcpToolName(registryId2, toolName) {
+  return `${registryId2}__${toolName}`;
+}
 var ProductAccessMode = z.enum(["local", "configured", "managed"]);
 var BillingMode = z.enum(["disabled", "stripe"]);
 var EntitlementsMode = z.enum(["none", "static", "managed"]);
@@ -450,12 +473,40 @@ var Workspace = z.object({
   // Per-workspace agent persona template (white-label override). null means
   // the deployment default (OPENGENI_AGENT_INSTRUCTIONS_TEMPLATE /
   // DEFAULT_AGENT_INSTRUCTIONS) is used. The runtime always injects the
-  // non-bypassable CORE (goal-loop ownership + environment block), so an
+  // non-bypassable CORE (goal-loop ownership + variableSet block), so an
   // override restyles the persona without dropping that contract.
   agentInstructions: z.string().nullable(),
+  // Growth-ready per-workspace settings bag (migration 0045). Known keys are
+  // validated by WorkspaceSettingsSchema; unknown keys are preserved across
+  // PATCH merges so newer settings survive an older server.
+  settings: z.record(z.string(), z.unknown()),
+  inferenceState: z.enum(["active", "paused"]),
+  inferenceGeneration: z.number().int().nonnegative(),
+  inferenceReason: z.string().nullable(),
+  inferenceChangedBy: z.string().nullable(),
+  inferenceChangedAt: z.string().nullable(),
+  // Workspace default rig used by session/scheduled-task create fallback.
+  defaultRigId: z.string().uuid().nullable(),
   createdAt: z.string(),
   updatedAt: z.string()
 });
+var WorkspaceSettingsSchema = z.object({
+  memoryEnabled: z.boolean().optional()
+}).passthrough();
+function resolveWorkspaceMemoryEnabled(settings) {
+  const parsed = WorkspaceSettingsSchema.safeParse(settings ?? {});
+  return parsed.success ? parsed.data.memoryEnabled === true : false;
+}
+var UpdateWorkspaceSettingsRequest = z.object({
+  memoryEnabled: z.boolean().optional()
+}).passthrough();
+var SetWorkspaceDefaultRigRequest = z.object({
+  rigId: z.string().uuid().nullable()
+});
+var UpdateWorkspaceModelPolicyRequest = z.object({
+  allowedProviders: z.array(z.string().min(1).max(128)).max(64).nullable().optional(),
+  allowedModels: z.array(z.string().min(1).max(256)).max(256).nullable().optional()
+});
 var AccountGrant = z.object({
   accountId: z.string().uuid(),
   subjectId: z.string().min(1),
@@ -490,10 +541,18 @@ var DelegatedAccessTokenPayload = z.object({
   // Worker-asserted session scope for first-party MCP calls (HMAC-signed, not
   // agent-controlled); enables session-scoped tools such as goal management.
   sessionId: z.string().uuid().optional(),
+  // The turn making the call (the caller's identity), HMAC-signed by the worker
+  // at turn setup. Lets a tool classify WHO is calling from the token itself,
+  // instead of racily re-reading the session's live active_turn_id — e.g. the
+  // sacred-pause guard must know if the CALLER is a machine child-notification
+  // turn, and the active pointer can flip to another turn mid-check.
+  turnId: z.string().uuid().optional(),
   exp: z.number().int().positive()
 });
 async function signDelegatedAccessToken(secret, payload) {
-  const encodedPayload = base64UrlEncode(JSON.stringify(DelegatedAccessTokenPayload.parse(payload)));
+  const encodedPayload = base64UrlEncode(
+    JSON.stringify(DelegatedAccessTokenPayload.parse(payload))
+  );
   const signature = await hmacSha256Base64Url(secret, encodedPayload);
   return `ogd_${encodedPayload}.${signature}`;
 }
@@ -512,7 +571,9 @@ async function verifyDelegatedAccessToken(secret, token, nowSeconds = Math.floor
   if (!constantTimeEqual(signature, expected)) {
     return null;
   }
-  const payload = DelegatedAccessTokenPayload.safeParse(JSON.parse(base64UrlDecode(encodedPayload)));
+  const payload = DelegatedAccessTokenPayload.safeParse(
+    JSON.parse(base64UrlDecode(encodedPayload))
+  );
   if (!payload.success || payload.data.exp < nowSeconds) {
     return null;
   }
@@ -808,8 +869,24 @@ var LimitDecision = z.discriminatedUnion("allowed", [
 ]);
 var EntitlementDecision = z.discriminatedUnion("allowed", [
   z.object({ allowed: z.literal(true), quantity: z.number().optional() }),
-  z.object({ allowed: z.literal(false), reason: z.string(), code: z.string().optional(), quantity: z.number().optional() })
+  z.object({
+    allowed: z.literal(false),
+    reason: z.string(),
+    code: z.string().optional(),
+    quantity: z.number().optional()
+  })
 ]);
+var GitCredentialProvider = z.enum(["github", "gitlab", "azure_devops"]);
+var GitProviderRepositoryId = z.union([z.number().int().positive(), z.string().min(1)]);
+var GitCredentialRepositoryRef = z.object({
+  provider: GitCredentialProvider.optional(),
+  uri: z.string().min(1),
+  ref: z.string().min(1),
+  repositoryId: GitProviderRepositoryId.optional(),
+  installationId: GitProviderRepositoryId.optional(),
+  projectId: GitProviderRepositoryId.optional(),
+  connectionId: z.string().min(1).optional()
+});
 var BillingBalance = z.object({
   accountId: z.string().uuid(),
   balanceMicros: z.number().int(),
@@ -835,6 +912,11 @@ var RepositoryResourceRef = z.object({
   ref: z.string().min(1),
   mountPath: z.string().min(1).optional(),
   subpath: z.string().min(1).optional(),
+  provider: GitCredentialProvider.optional(),
+  repositoryId: GitProviderRepositoryId.optional(),
+  installationId: GitProviderRepositoryId.optional(),
+  projectId: GitProviderRepositoryId.optional(),
+  connectionId: z.string().min(1).optional(),
   githubInstallationId: z.number().int().positive().optional(),
   githubRepositoryId: z.number().int().positive().optional()
 });
@@ -845,7 +927,13 @@ var FileResourceRef = z.object({
 });
 var ResourceRef = z.discriminatedUnion("kind", [RepositoryResourceRef, FileResourceRef]);
 var FileStatus = z.enum(["pending_upload", "ready", "failed", "expired", "deleted"]);
-var FileUploadStatus = z.enum(["pending", "completed", "expired", "failed"]);
+var FileUploadStatus = z.enum([
+  "pending",
+  "cleanup_pending",
+  "completed",
+  "expired",
+  "failed"
+]);
 var FileAsset = z.object({
   id: z.string().uuid(),
   workspaceId: z.string().uuid(),
@@ -882,6 +970,17 @@ var FileDownloadUrlResponse = z.object({
   expiresAt: z.string()
 });
 var DocumentStatus = z.enum(["queued", "indexing", "ready", "failed"]);
+var KnowledgeSourceKind = z.enum([
+  "manual_upload",
+  "meeting_transcript",
+  "repository",
+  "email",
+  "chat",
+  "document",
+  "web",
+  "other"
+]);
+var DocumentSearchMode = z.enum(["hybrid", "vector", "keyword"]);
 var DocumentBase = z.object({
   id: z.string().uuid(),
   workspaceId: z.string().uuid(),
@@ -900,6 +999,15 @@ var Document = z.object({
   parser: z.string(),
   chunkCount: z.number().int().nonnegative(),
   error: z.string().nullable(),
+  sourceKind: KnowledgeSourceKind,
+  sourceUri: z.string().nullable(),
+  sourceExternalId: z.string().nullable(),
+  sourceTitle: z.string().nullable(),
+  sourceAuthor: z.string().nullable(),
+  sourceCreatedAt: z.string().nullable(),
+  sourceUpdatedAt: z.string().nullable(),
+  sourceVersion: z.string().nullable(),
+  aclTags: z.array(z.string()),
   createdAt: z.string(),
   updatedAt: z.string()
 });
@@ -912,19 +1020,142 @@ var DocumentSearchResult = z.object({
   title: z.string(),
   text: z.string(),
   score: z.number(),
+  matchType: DocumentSearchMode,
+  vectorScore: z.number().nullable(),
+  keywordScore: z.number().nullable(),
   chunkIndex: z.number().int().nonnegative(),
-  metadata: z.record(z.string(), z.unknown())
+  metadata: z.record(z.string(), z.unknown()),
+  sourceKind: KnowledgeSourceKind,
+  sourceUri: z.string().nullable(),
+  sourceExternalId: z.string().nullable(),
+  sourceTitle: z.string().nullable(),
+  sourceAuthor: z.string().nullable(),
+  sourceCreatedAt: z.string().nullable(),
+  sourceUpdatedAt: z.string().nullable(),
+  sourceVersion: z.string().nullable(),
+  aclTags: z.array(z.string())
 });
 var CreateDocumentBaseRequest = z.object({
   name: z.string().min(1),
   description: z.string().optional()
 });
 var AddDocumentRequest = z.object({
-  fileId: z.string().uuid()
+  fileId: z.string().uuid(),
+  title: z.string().min(1).optional(),
+  sourceKind: KnowledgeSourceKind.optional(),
+  sourceUri: z.string().min(1).optional(),
+  sourceExternalId: z.string().min(1).optional(),
+  sourceTitle: z.string().min(1).optional(),
+  sourceAuthor: z.string().min(1).optional(),
+  sourceCreatedAt: z.string().datetime({ offset: true }).optional(),
+  sourceUpdatedAt: z.string().datetime({ offset: true }).optional(),
+  sourceVersion: z.string().min(1).optional(),
+  aclTags: z.array(z.string().min(1)).optional()
 });
 var DocumentSearchRequest = z.object({
   query: z.string().min(1),
-  limit: z.number().int().positive().max(20).default(5)
+  baseIds: z.array(z.string().uuid()).optional(),
+  mode: DocumentSearchMode.optional(),
+  sourceKinds: z.array(KnowledgeSourceKind).optional(),
+  aclTags: z.array(z.string().min(1)).optional(),
+  limit: z.number().int().positive().max(50).default(5)
+});
+var KnowledgeMemoryStatus = z.enum([
+  "proposed",
+  "approved",
+  "rejected",
+  "active",
+  "superseded",
+  "archived"
+]);
+var KnowledgeMemoryKind = z.enum([
+  "semantic",
+  "episodic",
+  "procedural",
+  "decision",
+  "preference"
+]);
+var KnowledgeSourceRef = z.object({
+  kind: z.enum(["document_chunk", "document", "session_event", "memory", "external"]),
+  id: z.string().min(1),
+  uri: z.string().min(1).optional(),
+  title: z.string().min(1).optional(),
+  metadata: z.record(z.string(), z.unknown()).default({})
+});
+var KnowledgeMemory = z.object({
+  id: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  status: KnowledgeMemoryStatus,
+  kind: KnowledgeMemoryKind,
+  scope: z.string(),
+  text: z.string(),
+  sourceRefs: z.array(KnowledgeSourceRef),
+  confidence: z.number().min(0).max(1),
+  metadata: z.record(z.string(), z.unknown()),
+  createdBySessionId: z.string().uuid().nullable(),
+  reviewedBy: z.string().nullable(),
+  reviewedAt: z.string().nullable(),
+  // Workspace Memory V1 fields. usageCount/lastUsedAt feed end-state ranking and
+  // decay; supersedesId/supersededById link correction chains; validFrom/validUntil
+  // are the point-in-time window. embedding/embeddingModel/textHash are internal
+  // and never exposed on the wire.
+  pinned: z.boolean(),
+  usageCount: z.number().int(),
+  lastUsedAt: z.string().nullable(),
+  supersedesId: z.string().uuid().nullable(),
+  supersededById: z.string().uuid().nullable(),
+  validFrom: z.string(),
+  validUntil: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string()
+});
+var CreateKnowledgeMemoryRequest = z.object({
+  status: KnowledgeMemoryStatus.default("active"),
+  kind: KnowledgeMemoryKind.default("semantic"),
+  scope: z.string().min(1).default("workspace"),
+  text: z.string().min(1),
+  sourceRefs: z.array(KnowledgeSourceRef).default([]),
+  confidence: z.number().min(0).max(1).default(0.5),
+  metadata: z.record(z.string(), z.unknown()).default({}),
+  createdBySessionId: z.string().uuid().optional(),
+  pinned: z.boolean().optional(),
+  replacesId: z.string().min(1).optional()
+});
+var UpdateKnowledgeMemoryRequest = z.object({
+  status: KnowledgeMemoryStatus.optional(),
+  kind: KnowledgeMemoryKind.optional(),
+  scope: z.string().min(1).optional(),
+  text: z.string().min(1).optional(),
+  sourceRefs: z.array(KnowledgeSourceRef).optional(),
+  confidence: z.number().min(0).max(1).optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  reviewedBy: z.string().min(1).optional(),
+  // Human audit action: pin (never decays) / unpin.
+  pinned: z.boolean().optional()
+});
+var KnowledgeMemorySearchRequest = z.object({
+  query: z.string().min(1).optional(),
+  status: KnowledgeMemoryStatus.optional(),
+  kind: KnowledgeMemoryKind.optional(),
+  scope: z.string().min(1).optional(),
+  limit: z.number().int().positive().max(100).default(20)
+});
+var WorkspaceMemorySearchMode = z.enum(["hybrid", "vector", "keyword"]);
+var WorkspaceMemorySearchRequest = z.object({
+  query: z.string().min(1),
+  kind: KnowledgeMemoryKind.optional(),
+  limit: z.number().int().positive().max(20).optional(),
+  mode: WorkspaceMemorySearchMode.optional()
+});
+var WorkspaceMemorySearchResult = z.object({
+  memory: KnowledgeMemory,
+  score: z.number(),
+  matchType: WorkspaceMemorySearchMode,
+  vectorScore: z.number().nullable(),
+  keywordScore: z.number().nullable()
+});
+var WorkspaceMemorySearchResponse = z.object({
+  results: z.array(WorkspaceMemorySearchResult)
 });
 var ToolRef = z.object({
   kind: z.literal("mcp"),
@@ -938,13 +1169,16 @@ var ToolRef = z.object({
   optional: z.boolean().optional()
 });
 var registryId = /^[A-Za-z0-9_-]+$/;
-var httpsUrl = z.string().url().refine((value) => {
-  try {
-    return new URL(value).protocol === "https:";
-  } catch {
-    return false;
-  }
-}, { message: "URL must use https" });
+var httpsUrl = z.string().url().refine(
+  (value) => {
+    try {
+      return new URL(value).protocol === "https:";
+    } catch {
+      return false;
+    }
+  },
+  { message: "URL must use https" }
+);
 var SessionMcpServerInput = z.object({
   id: z.string().min(1).regex(registryId),
   name: z.string().min(1).optional(),
@@ -952,6 +1186,12 @@ var SessionMcpServerInput = z.object({
   allowedTools: z.array(z.string().min(1)).optional(),
   timeoutMs: z.number().int().positive().optional(),
   cacheToolsList: z.boolean().optional(),
+  // Human-approval policy for this server's tools. `true` = every tool of this
+  // server requires approval before it runs (a `session.requiresAction` pause
+  // the caller resolves with `user.approvalDecision`); a string[] = ONLY the
+  // listed UNPREFIXED tool names require approval (e.g. reads auto-run, writes
+  // ask); absent / `false` = auto-run everything (the historical default).
+  requireApproval: z.union([z.boolean(), z.array(z.string().min(1))]).optional(),
   // Write-only credential headers. Values are encrypted at rest and never
   // returned in session responses or events; response metadata exposes names.
   headers: z.record(z.string(), z.string()).optional()
@@ -993,8 +1233,14 @@ function mergeToolRefs(existing, additions) {
 }
 function mergeResourceRefs(existing, additions, options = {}) {
   const out = [...existing];
-  const mountPaths = new Map(existing.flatMap((resource) => resource.mountPath ? [[resource.mountPath, stableJson(resource)]] : []));
-  const identities = new Map(existing.map((resource) => [resourceIdentityKey(resource), stableJson(resource)]));
+  const mountPaths = new Map(
+    existing.flatMap(
+      (resource) => resource.mountPath ? [[resource.mountPath, stableJson(resource)]] : []
+    )
+  );
+  const identities = new Map(
+    existing.map((resource) => [resourceIdentityKey(resource), stableJson(resource)])
+  );
   const exact = new Set(existing.map(stableJson));
   for (const resource of additions) {
     const serialized = stableJson(resource);
@@ -1004,12 +1250,16 @@ function mergeResourceRefs(existing, additions, options = {}) {
     if (options.rejectConflicts) {
       const existingAtMount = resource.mountPath ? mountPaths.get(resource.mountPath) : void 0;
       if (existingAtMount && existingAtMount !== serialized) {
-        throw new ResourceRefConflictError(`resource mount path is already attached: ${resource.mountPath}`);
+        throw new ResourceRefConflictError(
+          `resource mount path is already attached: ${resource.mountPath}`
+        );
       }
       const identity = resourceIdentityKey(resource);
       const existingIdentity = identities.get(identity);
       if (existingIdentity && existingIdentity !== serialized) {
-        throw new ResourceRefConflictError(`resource is already attached with different settings: ${identity}`);
+        throw new ResourceRefConflictError(
+          `resource is already attached with different settings: ${identity}`
+        );
       }
     }
     out.push(resource);
@@ -1039,17 +1289,38 @@ function sortJson(value) {
     return value.map(sortJson);
   }
   if (value && typeof value === "object") {
-    return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, nested]) => [key, sortJson(nested)]));
+    return Object.fromEntries(
+      Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, nested]) => [key, sortJson(nested)])
+    );
   }
   return value;
 }
-var SessionTurnStatus = z.enum(["queued", "running", "requires_action", "completed", "failed", "cancelled"]);
-var SessionTurnSource = z.enum(["user", "scheduled_task", "api", "goal"]);
+var SessionTurnStatus = z.enum([
+  "queued",
+  "running",
+  "requires_action",
+  "recovering",
+  "waiting_capacity",
+  "completed",
+  "failed",
+  "cancelled",
+  "superseded"
+]);
+var SessionTurnSource = z.enum([
+  "user",
+  "scheduled_task",
+  "api",
+  "goal",
+  "system",
+  "compaction"
+]);
+var SessionControlState = z.enum(["active", "paused"]);
+var WorkspaceInferenceState = z.enum(["active", "paused"]);
 var SessionGoalStatus = z.enum(["active", "paused", "completed"]);
 var SessionGoalCreatedBy = z.enum(["api", "agent", "scheduled_task"]);
 var SessionGoalPausedReason = z.enum([
   "agent",
-  "user_interrupt",
+  "user_pause",
   "api",
   "no_progress",
   "max_auto_continuations",
@@ -1087,6 +1358,10 @@ var UpdateSessionGoalRequest = z.object({
 var UpdateSessionRequest = z.object({
   title: z.string().min(1).max(200)
 });
+var UpdateSessionPinRequest = z.object({
+  pinned: z.boolean(),
+  expectedVersion: z.number().int().nonnegative().optional()
+});
 var ClearSessionContextRequest = z.object({
   confirm: z.literal(true)
 });
@@ -1105,9 +1380,10 @@ function isClearedRunStateBlob(serialized) {
 }
 var CompactSessionContextRequest = z.object({}).strict();
 var CompactSessionContextResult = z.object({
-  // queued: a client-side (Azure) compaction will run before the next turn.
-  // noop:   nothing to do (server-managed provider, mode off, or no history).
-  status: z.enum(["queued", "noop"]),
+  // pending: an active/paused session will compact at its next safe boundary.
+  // completed: an idle compaction-only activity completed synchronously.
+  // noop: there is no active history to compact.
+  status: z.enum(["pending", "completed", "noop"]),
   message: z.string()
 });
 var SessionTurn = z.object({
@@ -1118,7 +1394,7 @@ var SessionTurn = z.object({
   temporalWorkflowId: z.string(),
   status: SessionTurnStatus,
   source: SessionTurnSource,
-  position: z.number().int().positive(),
+  position: z.number().int(),
   prompt: z.string().min(1),
   resources: z.array(ResourceRef),
   tools: z.array(ToolRef),
@@ -1128,55 +1404,232 @@ var SessionTurn = z.object({
   // 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()),
+  cancelledBy: z.string().nullable(),
+  cancelReason: z.string().nullable(),
   startedAt: z.string().nullable(),
   finishedAt: z.string().nullable(),
   createdAt: z.string(),
   updatedAt: z.string()
 });
-var UpdateSessionTurnRequest = z.object({
-  prompt: z.string().min(1).optional(),
-  resources: z.array(ResourceRef).optional(),
-  tools: z.array(ToolRef).optional(),
-  model: z.string().min(1).optional(),
-  reasoningEffort: ReasoningEffort.optional(),
-  sandboxBackend: SandboxBackend.optional(),
-  metadata: z.record(z.string(), z.unknown()).optional()
-});
-var ReorderSessionTurnsRequest = z.object({
-  turnIds: z.array(z.string().uuid()).min(1)
+var SessionQueueSnapshot = z.object({
+  version: z.number().int().nonnegative(),
+  controlState: SessionControlState,
+  controlGeneration: z.number().int().nonnegative(),
+  workspaceInferenceState: WorkspaceInferenceState,
+  workspaceInferenceGeneration: z.number().int().nonnegative(),
+  workspaceRunExceptionGeneration: z.number().int().nonnegative().nullable(),
+  items: z.array(SessionTurn)
+});
+var CancelSessionQueueItemRequest = z.object({
+  expectedQueueVersion: z.number().int().nonnegative(),
+  expectedItemVersion: z.number().int().positive(),
+  reason: z.string().min(1).optional()
+});
+var SessionControlRequest = z.object({
+  mode: z.enum(["pause", "resume"]),
+  reason: z.string().min(1).optional(),
+  clientEventId: z.string().min(1).optional(),
+  expectedControlState: SessionControlState.optional(),
+  expectedControlGeneration: z.number().int().nonnegative().optional(),
+  expectedWorkspaceInferenceGeneration: z.number().int().nonnegative().optional()
+});
+var WorkspaceInferenceControlRequest = z.object({
+  state: WorkspaceInferenceState,
+  reason: z.string().min(1),
+  clientEventId: z.string().min(1),
+  expectedState: WorkspaceInferenceState,
+  expectedGeneration: z.number().int().nonnegative(),
+  exceptSessionIds: z.array(z.string().uuid()).default([])
+});
+var WorkspaceInferenceControlResponse = z.object({
+  operationId: z.string().uuid(),
+  state: WorkspaceInferenceState,
+  generation: z.number().int().nonnegative(),
+  affectedSessionIds: z.array(z.string().uuid()),
+  controlSessionIds: z.array(z.string().uuid()),
+  exceptionSessionIds: z.array(z.string().uuid())
+});
+var SystemUpdateClassification = z.enum(["success", "failure", "action_required", "info"]);
+var SessionSystemUpdateKind = z.enum([
+  "child_session_update",
+  "scheduled_wake",
+  "lifecycle_event",
+  "runtime_notice"
+]);
+var SessionSystemUpdateState = z.enum([
+  "pending",
+  "deferred",
+  "delivered",
+  "cancelled",
+  "failed"
+]);
+var SessionSystemUpdate = z.object({
+  id: z.string().uuid(),
+  sessionId: z.string().uuid(),
+  kind: SessionSystemUpdateKind,
+  classification: SystemUpdateClassification,
+  sourceId: z.string(),
+  dedupeKey: z.string(),
+  summary: z.string(),
+  payload: z.record(z.string(), z.unknown()),
+  lineage: z.record(z.string(), z.unknown()),
+  state: SessionSystemUpdateState,
+  deliveredTurnId: z.string().uuid().nullable(),
+  deliveredAt: z.string().nullable(),
+  createdAt: z.string()
 });
-var WorkspaceEnvironmentVariableName = z.string().regex(/^[A-Z][A-Z0-9_]*$/).max(128);
-var WorkspaceEnvironmentVariableMetadata = z.object({
-  name: WorkspaceEnvironmentVariableName,
+var VariableSetVariableName = z.string().regex(/^[A-Z][A-Z0-9_]*$/).max(128);
+function withVariableSetIdAlias(shape) {
+  return z.preprocess((input) => {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+      return input;
+    }
+    const record = input;
+    if (record.variableSetId !== void 0 || record.environmentId === void 0) {
+      return record;
+    }
+    return { ...record, variableSetId: record.environmentId };
+  }, z.object(shape));
+}
+var VariableSetVariableMetadata = z.object({
+  name: VariableSetVariableName,
   version: z.number().int().positive(),
   createdAt: z.string(),
   updatedAt: z.string()
 });
-var WorkspaceEnvironment = z.object({
+var WorkspaceEnvironmentVariableMetadata = VariableSetVariableMetadata;
+var VariableSet = z.object({
   id: z.string().uuid(),
   accountId: z.string().uuid(),
   workspaceId: z.string().uuid(),
   name: z.string(),
   description: z.string().nullable(),
-  variables: z.array(WorkspaceEnvironmentVariableMetadata),
+  variables: z.array(VariableSetVariableMetadata),
   createdAt: z.string(),
   updatedAt: z.string()
 });
-var CreateWorkspaceEnvironmentRequest = z.object({
+var WorkspaceEnvironment = VariableSet;
+var CreateVariableSetRequest = z.object({
   name: z.string().min(1).max(120),
   description: z.string().max(2e3).optional(),
-  variables: z.array(z.object({
-    name: WorkspaceEnvironmentVariableName,
-    value: z.string().min(1).max(32768)
-  })).default([])
+  variables: z.array(
+    z.object({
+      name: VariableSetVariableName,
+      value: z.string().min(1).max(32768)
+    })
+  ).default([])
 });
-var UpdateWorkspaceEnvironmentRequest = z.object({
+var CreateWorkspaceEnvironmentRequest = CreateVariableSetRequest;
+var UpdateVariableSetRequest = z.object({
   name: z.string().min(1).max(120).optional(),
   description: z.string().max(2e3).nullable().optional()
 });
-var SetWorkspaceEnvironmentVariableRequest = z.object({
+var UpdateWorkspaceEnvironmentRequest = UpdateVariableSetRequest;
+var SetVariableSetVariableRequest = z.object({
   value: z.string().min(1).max(32768)
 });
+var SetWorkspaceEnvironmentVariableRequest = SetVariableSetVariableRequest;
+var RigCheck = z.object({
+  name: z.string().min(1).max(120),
+  command: z.string().min(1).max(8192)
+});
+var 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()
+});
+var RigVerificationHealth = z.object({
+  checkHealth: z.enum(["passing", "failing", "unknown"]),
+  lastVerifiedAt: z.string().nullable()
+});
+var 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()
+});
+var RigChangeKind = z.enum(["setup_append", "definition_edit"]);
+var RigChangeStatus = z.enum(["proposed", "verifying", "merged", "rejected", "failed"]);
+var RigCheckResult = z.object({
+  name: z.string(),
+  command: z.string(),
+  exitCode: z.number().int().nullable(),
+  output: z.string().optional()
+});
+var RigChangeVerification = z.object({
+  startedAt: z.string().optional(),
+  finishedAt: z.string().optional(),
+  log: z.string().optional(),
+  checkResults: z.array(RigCheckResult).optional()
+}).passthrough();
+var RigChange = z.object({
+  id: z.string().uuid(),
+  rigId: z.string().uuid(),
+  baseVersionId: z.string().uuid().nullable(),
+  kind: RigChangeKind,
+  payload: z.record(z.string(), z.unknown()),
+  status: RigChangeStatus,
+  proposedBy: z.string().nullable(),
+  verification: RigChangeVerification.nullable(),
+  resultVersionId: z.string().uuid().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string()
+});
+var CreateRigRequest = z.object({
+  name: z.string().min(1).max(120),
+  description: z.string().max(2e3).optional(),
+  // Initial (version 1) content, inline.
+  image: z.string().max(1024).optional(),
+  setupScript: z.string().max(131072).optional(),
+  checks: z.array(RigCheck).max(100).default([]),
+  credentialHooks: z.array(z.string().min(1).max(200)).max(50).default([]),
+  defaultVariableSetIds: z.array(z.string().uuid()).max(25).default([])
+});
+var UpdateRigRequest = z.object({
+  name: z.string().min(1).max(120).optional(),
+  description: z.string().max(2e3).nullable().optional()
+});
+var RigSetupAppendPayload = z.object({
+  command: z.string().min(1).max(8192),
+  note: z.string().max(2e3).optional()
+});
+var RigDefinitionEditPayload = z.object({
+  image: z.string().max(1024).nullish(),
+  setupScript: z.string().max(131072).nullish(),
+  checks: z.array(RigCheck).max(100).optional(),
+  credentialHooks: z.array(z.string().min(1).max(200)).max(50).optional(),
+  defaultVariableSetIds: z.array(z.string().uuid()).max(25).optional(),
+  changelog: z.string().max(4096).nullish()
+});
+var ProposeRigChangeRequest = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("setup_append"), payload: RigSetupAppendPayload }),
+  z.object({ kind: z.literal("definition_edit"), payload: RigDefinitionEditPayload })
+]);
 var ScheduledTaskStatus = z.enum(["active", "paused"]);
 var ScheduledTaskRunStatus = z.enum(["queued", "dispatched", "failed"]);
 var ScheduledTaskRunMode = z.enum(["new_session_per_run", "reusable_session"]);
@@ -1224,7 +1677,13 @@ var ScheduledTask = z.object({
   overlapPolicy: ScheduledTaskOverlapPolicy,
   agentConfig: ScheduledTaskAgentConfig,
   reusableSessionId: z.string().uuid().nullable(),
-  environmentId: z.string().uuid().nullable(),
+  variableSetId: z.string().uuid().nullable().default(null),
+  /** @deprecated use variableSetId */
+  environmentId: z.string().uuid().nullable().default(null),
+  // The rig each run binds to (M3). Stored on the task; the ACTIVE version is
+  // resolved PER FIRE (at dispatch), so a task always runs the rig's current
+  // version rather than one frozen at task-create time. Null ⇒ rig-less runs.
+  rigId: z.string().uuid().nullable().default(null),
   metadata: z.record(z.string(), z.unknown()),
   createdAt: z.string(),
   updatedAt: z.string()
@@ -1244,24 +1703,31 @@ var ScheduledTaskRun = z.object({
   createdAt: z.string(),
   updatedAt: z.string()
 });
-var CreateScheduledTaskRequest = z.object({
+var CreateScheduledTaskRequest = withVariableSetIdAlias({
   name: z.string().min(1),
   schedule: ScheduledTaskScheduleSpec,
   runMode: ScheduledTaskRunMode.default("new_session_per_run"),
   overlapPolicy: ScheduledTaskOverlapPolicy.default("allow_concurrent"),
   agentConfig: ScheduledTaskAgentConfig,
   status: ScheduledTaskStatus.default("active"),
+  variableSetId: z.string().uuid().nullable().optional(),
   environmentId: z.string().uuid().nullable().optional(),
+  // The rig each run binds to (M3); its active version is resolved per fire.
+  rigId: z.string().uuid().nullable().optional(),
   metadata: z.record(z.string(), z.unknown()).default({})
 });
-var UpdateScheduledTaskRequest = z.object({
+var UpdateScheduledTaskRequest = withVariableSetIdAlias({
   name: z.string().min(1).optional(),
   schedule: ScheduledTaskScheduleSpec.optional(),
   runMode: ScheduledTaskRunMode.optional(),
   overlapPolicy: ScheduledTaskOverlapPolicy.optional(),
   agentConfig: ScheduledTaskAgentConfig.optional(),
   status: ScheduledTaskStatus.optional(),
+  variableSetId: z.string().uuid().nullable().optional(),
   environmentId: z.string().uuid().nullable().optional(),
+  // The rig each run binds to (M3); null clears it. Its active version is
+  // resolved per fire, so an update takes effect on the next dispatch.
+  rigId: z.string().uuid().nullable().optional(),
   metadata: z.record(z.string(), z.unknown()).optional()
 });
 var TriggerScheduledTaskRequest = z.object({
@@ -1317,12 +1783,20 @@ var CapabilityPackSkill = z.object({
   const seen = /* @__PURE__ */ new Set();
   skill.files.forEach((file, index) => {
     if (seen.has(file.path)) {
-      ctx.addIssue({ code: "custom", message: `duplicate skill file path: ${file.path}`, path: ["files", index, "path"] });
+      ctx.addIssue({
+        code: "custom",
+        message: `duplicate skill file path: ${file.path}`,
+        path: ["files", index, "path"]
+      });
     }
     seen.add(file.path);
   });
   if (!skill.files.some((file) => file.path === "SKILL.md")) {
-    ctx.addIssue({ code: "custom", message: "skill must include a top-level SKILL.md file", path: ["files"] });
+    ctx.addIssue({
+      code: "custom",
+      message: "skill must include a top-level SKILL.md file",
+      path: ["files"]
+    });
   }
 });
 function isSafePackSkillRelativePath(path) {
@@ -1331,39 +1805,71 @@ function isSafePackSkillRelativePath(path) {
   }
   return path.split("/").every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
 }
-var CapabilityPack = z.object({
-  id: z.string().min(1),
-  name: z.string().min(1),
+var CapabilityPackVariableSet = z.object({
   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.
-  sandboxImage: z.string().trim().min(1).max(512).optional(),
-  // Skills delivered into the sandbox skill index when the pack is enabled.
-  skills: z.array(CapabilityPackSkill).max(32).superRefine((skills, ctx) => {
-    const seen = /* @__PURE__ */ new Set();
-    skills.forEach((skill, index) => {
-      const key = skill.name.toLowerCase();
-      if (seen.has(key)) {
-        ctx.addIssue({ code: "custom", message: `duplicate pack skill name: ${skill.name}`, path: [index, "name"] });
-      }
-      seen.add(key);
-    });
-  }).default([]),
-  tools: z.array(ToolRef).default([]),
-  connectors: z.array(CapabilityPackConnector).default([]),
-  knowledge: z.array(CapabilityPackKnowledge).default([]),
-  scheduledTaskTemplates: z.array(CapabilityPackScheduledTaskTemplate).default([]),
-  environment: z.object({
-    description: z.string().min(1),
-    requiredVariables: z.array(WorkspaceEnvironmentVariableName).default([]),
-    required: z.boolean().default(false)
-  }).optional(),
-  metadata: z.record(z.string(), z.unknown()).default({})
+  requiredVariables: z.array(VariableSetVariableName).default([]),
+  required: z.boolean().default(false)
 });
+var CapabilityPack = z.preprocess(
+  (input) => {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+      return input;
+    }
+    const record = input;
+    if (record.variableSet !== void 0) {
+      return record;
+    }
+    if (record.environment !== void 0) {
+      const { environment: _environment, ...rest } = record;
+      return { ...rest, variableSet: record.environment };
+    }
+    if (record.requiredVariables !== void 0) {
+      const { requiredVariables: _requiredVariables, ...rest } = record;
+      return {
+        ...rest,
+        variableSet: {
+          description: "Required variables",
+          requiredVariables: record.requiredVariables,
+          required: Array.isArray(record.requiredVariables) && record.requiredVariables.length > 0
+        }
+      };
+    }
+    return record;
+  },
+  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.
+    sandboxImage: z.string().trim().min(1).max(512).optional(),
+    // Skills delivered into the sandbox skill index when the pack is enabled.
+    skills: z.array(CapabilityPackSkill).max(32).superRefine((skills, ctx) => {
+      const seen = /* @__PURE__ */ new Set();
+      skills.forEach((skill, index) => {
+        const key = skill.name.toLowerCase();
+        if (seen.has(key)) {
+          ctx.addIssue({
+            code: "custom",
+            message: `duplicate pack skill name: ${skill.name}`,
+            path: [index, "name"]
+          });
+        }
+        seen.add(key);
+      });
+    }).default([]),
+    tools: z.array(ToolRef).default([]),
+    connectors: z.array(CapabilityPackConnector).default([]),
+    knowledge: z.array(CapabilityPackKnowledge).default([]),
+    scheduledTaskTemplates: z.array(CapabilityPackScheduledTaskTemplate).default([]),
+    variableSet: CapabilityPackVariableSet.optional(),
+    metadata: z.record(z.string(), z.unknown()).default({})
+  })
+);
 var RegisterCapabilityPackRequest = CapabilityPack;
 var WorkspaceRegisteredPack = z.object({
   accountId: z.string().uuid(),
@@ -1383,7 +1889,8 @@ var PackInstallation = z.object({
   enabledAt: z.string(),
   updatedAt: z.string()
 });
-var EnablePackRequest = z.object({
+var EnablePackRequest = withVariableSetIdAlias({
+  variableSetId: z.string().uuid().optional(),
   environmentId: z.string().uuid().optional(),
   metadata: z.record(z.string(), z.unknown()).default({})
 });
@@ -1449,6 +1956,91 @@ var CreateSocialPostRequest = z.object({
   metrics: z.record(z.string(), z.number()).default({}),
   raw: z.record(z.string(), z.unknown()).default({})
 });
+var ConnectionKind = z.enum(["oauth2", "api_key", "app_install", "delegated"]);
+var ConnectionStatus = z.enum(["active", "needs_reauth", "revoked", "error"]);
+var McpServerConnectionRef = z.object({
+  connectionId: z.string().uuid().optional(),
+  providerDomain: z.string().min(1),
+  kind: ConnectionKind.optional(),
+  scopes: z.array(z.string().min(1)).optional(),
+  resource: z.string().min(1).optional(),
+  subjectScope: z.enum(["workspace", "subject"]).optional()
+}).strict();
+var ConnectionMetadata = z.object({
+  id: z.string().uuid(),
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  subjectId: z.string().nullable(),
+  providerDomain: z.string(),
+  kind: ConnectionKind,
+  status: ConnectionStatus,
+  grantedScopes: z.array(z.string()),
+  expiresAt: z.string().nullable(),
+  lastRefreshAt: z.string().nullable(),
+  lastUsedAt: z.string().nullable(),
+  lastError: z.string().nullable(),
+  version: z.number().int().positive(),
+  metadata: z.record(z.string(), z.unknown()),
+  createdBySubjectId: z.string().nullable(),
+  updatedBySubjectId: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string()
+});
+var ConnectionCredentialBundle = z.record(z.string(), z.unknown());
+var CreateConnectionRequest = z.object({
+  providerDomain: z.string().min(1),
+  kind: ConnectionKind,
+  subjectId: z.string().min(1).nullable().optional(),
+  credential: ConnectionCredentialBundle,
+  grantedScopes: z.array(z.string().min(1)).default([]),
+  expiresAt: z.string().datetime({ offset: true }).nullable().optional(),
+  metadata: z.record(z.string(), z.unknown()).default({})
+});
+var UpdateConnectionRequest = z.object({
+  providerDomain: z.string().min(1).optional(),
+  subjectId: z.string().min(1).nullable().optional(),
+  kind: ConnectionKind.optional(),
+  status: ConnectionStatus.optional(),
+  credential: ConnectionCredentialBundle.optional(),
+  grantedScopes: z.array(z.string().min(1)).optional(),
+  expiresAt: z.string().datetime({ offset: true }).nullable().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional()
+});
+var ConnectionResponse = z.object({
+  connection: ConnectionMetadata
+});
+var ListConnectionsResponse = z.object({
+  connections: z.array(ConnectionMetadata)
+});
+var OAuthStartRequest = z.object({
+  providerDomain: z.string().min(1).optional(),
+  mcpUrl: z.string().url().optional(),
+  resource: z.string().url().optional(),
+  requestedScopes: z.array(z.string().min(1)).default([]),
+  returnPath: z.string().min(1).optional(),
+  connectionId: z.string().uuid().optional(),
+  oauthClient: z.object({
+    clientId: z.string().min(1),
+    clientSecret: z.string().min(1).optional(),
+    tokenEndpointAuthMethod: z.enum(["none", "client_secret_post", "client_secret_basic"]).optional()
+  }).optional()
+}).refine((value) => Boolean(value.mcpUrl ?? value.resource), {
+  message: "mcpUrl is required",
+  path: ["mcpUrl"]
+});
+var OAuthStartResponse = z.object({
+  state: z.string().min(1),
+  authorizationUrl: z.string().url().nullable(),
+  expiresAt: z.string()
+});
+var IntegrationClientMetadata = z.object({
+  client_id: z.string().url(),
+  client_name: z.literal("OpenGeni"),
+  redirect_uris: z.array(z.string().url()),
+  token_endpoint_auth_method: z.literal("none"),
+  grant_types: z.array(z.enum(["authorization_code", "refresh_token"])),
+  response_types: z.array(z.literal("code"))
+});
 var MarketingDailyAnalysisTaskRequest = z.object({
   name: z.string().min(1).optional(),
   connectionIds: z.array(z.string().uuid()).default([]),
@@ -1462,8 +2054,16 @@ var MarketingDailyAnalysisTaskRequest = z.object({
   overlapPolicy: ScheduledTaskOverlapPolicy.default("skip")
 });
 var CapabilityKind = z.enum(["pack", "mcp", "api", "skill", "plugin"]);
-var CapabilitySource = z.enum(["built_in", "configured", "public_registry", "manual"]);
+var CapabilitySource = z.enum([
+  "built_in",
+  "configured",
+  "public_registry",
+  "registry",
+  "manual"
+]);
 var CapabilityInstallationStatus = z.enum(["active", "disabled"]);
+var CapabilityCatalogAuthKind = z.enum(["oauth2", "api_key", "none", "unknown"]);
+var CapabilityCatalogTier = z.enum(["verified", "community"]);
 var CapabilityRuntime = z.object({
   available: z.boolean().default(false),
   mcpServerId: z.string().min(1).optional(),
@@ -1484,10 +2084,31 @@ var CapabilityCatalogItem = z.object({
   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 connection backing this enabled installation, when the enable-time
+  // connectionRef resolved to one (null for header/credential-free items —
+  // that means "no connection involved", not "broken"). Lets the UI match
+  // connection health by id instead of guessing from providerDomain alone.
+  connectionRef: z.object({
+    connectionId: z.string().min(1),
+    providerDomain: z.string().min(1),
+    kind: z.string().min(1)
+  }).nullable().default(null),
   metadata: z.record(z.string(), z.unknown()).default({}),
   createdAt: z.string().optional(),
   updatedAt: z.string().optional()
@@ -1518,22 +2139,24 @@ var CreateCapabilityCatalogItemRequest = z.object({
   authModel: z.string().min(1).optional(),
   metadata: z.record(z.string(), z.unknown()).default({})
 });
-var EnableCapabilityRequest = z.object({
+var 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-environments key, injected only into the runtime MCP client,
+   * 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 environment attachment for kind=pack capabilities. Mirrors the
+   * Initial variableSet attachment for kind=pack capabilities. Mirrors the
    * dedicated POST /packs/:id/enable body: required to enable an
-   * environment.required pack through the unified capability-enable path,
+   * 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()
 });
 var CapabilityCatalogResponse = z.object({
@@ -1575,7 +2198,16 @@ var Session = z.object({
   // stale in-flight op and retry against the new active sandbox.
   activeSandboxId: z.string().uuid().nullable(),
   activeEpoch: z.number().int().nonnegative(),
-  environmentId: z.string().uuid().nullable(),
+  variableSetId: z.string().uuid().nullable().default(null),
+  /** @deprecated use variableSetId */
+  environmentId: z.string().uuid().nullable().default(null),
+  // The rig this session rides (M3 runtime binding). Both are resolved and
+  // FROZEN at session create: rigId names the rig, rigVersionId pins the exact
+  // active version the session's box/env/setup/doctrine are built from for the
+  // session's whole life (a later promote does NOT move an existing session).
+  // Both null ⇒ a rig-less session (byte-for-byte today's behavior).
+  rigId: z.string().uuid().nullable().default(null),
+  rigVersionId: z.string().uuid().nullable().default(null),
   // Non-default first-party MCP token permissions (manager-style sessions);
   // null means the fixed worker default set.
   firstPartyMcpPermissions: z.array(Permission).nullable(),
@@ -1594,9 +2226,18 @@ var Session = z.object({
   temporalWorkflowId: z.string().nullable(),
   activeTurnId: z.string().uuid().nullable(),
   // Actual input tokens of the last model call of the most recent turn; the
-  // pre-turn client-side context-compaction trigger reads it as its budget
+  // pre-turn portable context-compaction trigger reads it as its budget
   // signal. Null until a turn with usage has completed.
   lastInputTokens: z.number().int().nonnegative().nullable(),
+  queueVersion: z.number().int().nonnegative(),
+  queueHeadPosition: z.number().int(),
+  queueTailPosition: z.number().int(),
+  controlState: SessionControlState,
+  controlGeneration: z.number().int().nonnegative(),
+  controlReason: z.string().nullable(),
+  controlChangedBy: z.string().nullable(),
+  controlChangedAt: z.string().nullable(),
+  workspaceRunExceptionGeneration: z.number().int().nonnegative().nullable(),
   lastSequence: z.number().int().nonnegative(),
   // Multi-account Codex (P1). codexPinnedCredentialId: the account this session is
   // manually PINNED to (null ⇒ follow the workspace active pointer).
@@ -1604,31 +2245,76 @@ var Session = z.object({
   // "Running on:" indicator's source). Both are credential-row ids, null until set.
   codexPinnedCredentialId: z.string().uuid().nullable(),
   codexLastCredentialId: z.string().uuid().nullable(),
+  /** Personal (authenticated subject) workspace pin state, never workspace-global. */
+  pinned: z.boolean().default(false),
+  /** Stable pin ordering key; null when this subject has not pinned the session. */
+  pinnedAt: z.string().nullable().default(null),
+  /** Optimistic pin-state revision; zero represents an absent pin relation. */
+  pinVersion: z.number().int().nonnegative().default(0),
+  /**
+   * Server-authoritative hierarchy summary populated on session-list reads.
+   * Detail reads may omit it. The rail uses this instead of guessing a tree
+   * from whichever global recency page happened to be loaded.
+   */
+  treeStats: 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()
+  }).optional(),
   createdAt: z.string(),
   updatedAt: z.string()
 });
+var SessionListResponse = z.object({
+  pinned: z.array(Session),
+  sessions: z.array(Session),
+  nextCursor: z.string().nullable()
+});
+var LineageNode = z.lazy(
+  () => z.object({
+    session: Session,
+    children: z.array(LineageNode)
+  })
+);
+var SessionLineageResponse = z.object({
+  ancestors: z.array(Session),
+  children: z.array(LineageNode),
+  truncated: z.boolean().default(false)
+});
 var SessionEventType = z.enum([
   "session.created",
   "session.status.changed",
   "session.requiresAction",
+  "session.context.compaction.requested",
   "session.context.compacted",
+  "session.context.compaction.skipped",
   "session.context.cleared",
   "user.message",
-  "user.interrupt",
+  "user.pause",
   "user.approvalDecision",
   "turn.queued",
-  "turn.updated",
   "turn.started",
   "turn.completed",
   "turn.failed",
   "turn.cancelled",
-  "turn.preempted",
+  "turn.superseded",
+  "turn.recovery.requested",
+  "turn.capacity_waiting",
   "agent.message.delta",
   "agent.message.completed",
   "agent.reasoning.delta",
   "agent.toolCall.created",
   "agent.toolCall.output",
+  "agent.model.usage",
+  "tool.auth_needed",
   "agent.updated",
+  "rig.setup.started",
+  "rig.setup.completed",
+  "rig.setup.skipped",
+  "rig.setup.failed",
   "sandbox.operation.started",
   "sandbox.operation.completed",
   "sandbox.operation.failed",
@@ -1639,7 +2325,22 @@ var SessionEventType = z.enum([
   "goal.completed",
   "goal.paused",
   "goal.resumed",
+  "goal.cleared",
   "goal.continuation",
+  "system.update.pending",
+  "system.update.delivered",
+  "session.control.paused",
+  "session.control.resumed",
+  "session.control.steer_requested",
+  "workspace.inference.paused",
+  "workspace.inference.resumed",
+  "session.queue.prompt.cancelled",
+  "session.queue.history",
+  // A terminal/stale activity callback is retained as an audit wrapper rather
+  // than being dropped or emitted as though it belonged to the current turn.
+  "turn.event.rejected_late",
+  "memory.saved",
+  "memory.corrected",
   // Channel-B desktop pixel-plane signals (07-channel-b §1.2). The pixel socket
   // carries opaque RFB and cannot carry a control message the client can act on,
   // so these ride the durable, sequenced, gap-filled Channel-A SSE spine.
@@ -1683,8 +2384,96 @@ var SessionEventType = z.enum([
   // Multi-account Codex (P1): the account a session's turn runs on changed
   // (manual switch in P1; failover/rotation in P3 reuse the same event). Drives
   // the in-session "Running on:" indicator's live flip.
-  "codex.account.switched"
+  "codex.account.switched",
+  // OPE-21 per-turn selection audit. Payload is metadata only: credential row
+  // id, bounded strategy/reason, and pool counts — never token material.
+  "codex.credential.selected",
+  // OPE-21 durable zero-capacity wait lifecycle. Runtime/system events only;
+  // no synthetic user message is created when capacity returns.
+  "codex.capacity.waiting",
+  "codex.capacity.resumed",
+  "codex.capacity.superseded",
+  // Sandbox durability observability (sandbox-file-persistence). The 2026-07
+  // incidents (mid-session box death with /workspace loss; a fatal manifest-env
+  // delta on a live box) were near-unattributable because box lifecycle left no
+  // durable trace — only worker logs, which rotate within hours. These events
+  // make every box transition and env recomputation drift readable from the DB
+  // alone. Payloads carry ids/flags/key NAMES only — never env values (secrets).
+  "sandbox.box.created",
+  // box cold-created/cold-restored ({hydrated: "archive"|"none"})
+  "sandbox.box.lost",
+  // resume-by-id found the box gone (provider NotFound)
+  "sandbox.box.terminated",
+  // reaper drain terminated the box ({actor, persisted})
+  "sandbox.box.snapshot",
+  // mid-session /workspace snapshot persisted ({trigger})
+  "sandbox.env.drift",
+  // recomputed manifest env != live box env (key names only)
+  // Active-sandbox pointer reconcile (issue #341 invariant B). Turn start found the
+  // persisted (active_sandbox_id, active_epoch) pointing at a target the turn cannot
+  // establish — a deleted/absent sandbox, a Modal sibling with no establisher, or a
+  // selfhosted sandbox with no enrollment — and reset it to the session HOME under
+  // the epoch fence instead of routing every op into the dead target. A VISIBLE,
+  // never-silent downgrade: payload carries the typed reason + from/to epoch, never a
+  // target id or command content. Announce-only; hits the timeline projection default
+  // (no rendered item) like the other sandbox.* diagnostics.
+  "session.route.reconciled",
+  // Workbench v2 turn-end workspace capture (dossier §10.1). ANNOUNCE-ONLY: a new
+  // capture revision was persisted at turn end; the client refetches the latest
+  // capture. It carries metadata only (revision/turnId/capturedAt/leaseEpoch/stats),
+  // never file content. Hits the timeline projection default case (ignored) — it
+  // must NEVER gain a rendered timeline item without regenerating the golden
+  // snapshots (dossier §7.3 golden-grammar gate).
+  "workspace.revision.captured",
+  // Repository discovery could not prove a complete capture. The worker
+  // persisted a failed/degraded revision marker and clients must fall back to
+  // the live box rather than trust a zero-repository snapshot.
+  "workspace.revision.degraded",
+  // Connected Machine (selfhosted) op-outcome observability (failure-visibility
+  // doctrine, out-of-band plane). SESSION-scoped facts only: these fire for the
+  // session whose turn ran the op (the two-planes rule — machine-plane facts like
+  // pressure live in the M10 metrics DB, never as session events). Payloads carry
+  // the op kind + a typed fault class + attempt count — NEVER command content.
+  //
+  // `machine.op.failed` fires ONLY for INFRASTRUCTURE fault classes (offline,
+  // draining-exhausted, payload-too-large, reconnecting-timeout, OS/stream/protocol)
+  // — a semantic miss the model asked about (a missing path, a consent gate, a
+  // nonzero exit) is an OUTCOME, not an infra fault, and never fires this.
+  // `machine.op.recovered` is the healed-fault leading indicator (a blip/backpressure
+  // the transport absorbed): announce-only, quiet. Both hit the timeline projection's
+  // quiet status-tick tier (the severity split's "degraded"); adding a rendered item
+  // requires regenerating the golden snapshots (the golden-grammar gate).
+  "machine.op.failed",
+  "machine.op.recovered",
+  // Connected Machine (selfhosted) LINK-plane observability (failure-visibility
+  // doctrine). SESSION-scoped, ANNOUNCE-ONLY facts fanned out to the sessions that
+  // had an active op running on the machine when its control link changed — never
+  // to idle/historical sessions. Payloads carry ids / a typed reason / key-names
+  // only, NEVER command content.
+  //
+  // `machine.link.lost` — the machine announced a clean GoingOffline (its control
+  // link is going away) while a session had a running turn on it. `machine.link.
+  // restored` — a reconnect Hello re-established the link that was previously lost.
+  // `machine.runner.restarted` — the additional signal that the going-offline was
+  // a self-update restart specifically (link.lost also fires for it; this
+  // distinguishes a restart from a plain stop / host shutdown). All three hit the
+  // timeline projection's quiet default tier (no rendered item); adding a rendered
+  // item requires regenerating the golden snapshots (the golden-grammar gate).
+  "machine.link.lost",
+  "machine.link.restored",
+  "machine.runner.restarted"
 ]);
+var ToolAuthNeededPayload = z.object({
+  serverId: z.string().min(1),
+  toolName: z.string().min(1).nullable().optional(),
+  providerDomain: z.string().min(1),
+  connectionId: z.string().uuid().nullable().optional(),
+  reason: z.enum(["missing_connection", "expired", "insufficient_scope", "refresh_failed"]),
+  scopes: z.array(z.string().min(1)).optional(),
+  resource: z.string().min(1).optional(),
+  authorizationUrl: z.string().url().optional(),
+  subjectId: z.string().min(1).nullable().optional()
+});
 var StreamUrlRotatedPayload = z.object({
   url: z.string().url(),
   token: z.string().nullable(),
@@ -1766,15 +2555,17 @@ var SandboxCommandOutputDeltaPayload = z.object({
 });
 var FsChangeKind = z.enum(["created", "modified", "deleted", "renamed"]);
 var FsChangedPayload = z.object({
-  changes: z.array(z.object({
-    path: z.string(),
-    // workspace-relative POSIX path
-    kind: FsChangeKind,
-    isDir: z.boolean().default(false),
-    sizeBytes: z.number().int().nonnegative().nullable().default(null),
-    oldPath: z.string().optional()
-    // for "renamed"
-  })).min(1),
+  changes: z.array(
+    z.object({
+      path: z.string(),
+      // workspace-relative POSIX path
+      kind: FsChangeKind,
+      isDir: z.boolean().default(false),
+      sizeBytes: z.number().int().nonnegative().nullable().default(null),
+      oldPath: z.string().optional()
+      // for "renamed"
+    })
+  ).min(1),
   source: z.enum(["write", "watch", "agent"]).default("write"),
   // Monotonic FS revision (per-lease, paired with leaseEpoch for staleness).
   revision: z.number().int().nonnegative(),
@@ -1817,16 +2608,18 @@ var TerminalPtyExitedPayload = z.object({
   reason: z.enum(["exit", "killed", "owner_gone", "timeout"])
 });
 var FsNodeType = z.enum(["file", "dir", "symlink", "other"]);
-var FsTreeNode = z.lazy(() => z.object({
-  name: z.string(),
-  path: z.string(),
-  type: FsNodeType,
-  sizeBytes: z.number().int().nonnegative().nullable(),
-  mtimeMs: z.number().int().nonnegative().nullable(),
-  mode: z.number().int().nullable(),
-  children: z.array(FsTreeNode).optional(),
-  truncated: z.boolean().default(false)
-}));
+var FsTreeNode = z.lazy(
+  () => z.object({
+    name: z.string(),
+    path: z.string(),
+    type: FsNodeType,
+    sizeBytes: z.number().int().nonnegative().nullable(),
+    mtimeMs: z.number().int().nonnegative().nullable(),
+    mode: z.number().int().nullable(),
+    children: z.array(FsTreeNode).optional(),
+    truncated: z.boolean().default(false)
+  })
+);
 var FsListRequest = z.object({
   path: z.string().default(""),
   // "" = workspace root
@@ -1985,6 +2778,125 @@ var GitDiffResponse = z.object({
   files: z.array(GitFileDiff),
   revision: z.number().int().nonnegative()
 });
+var WorkspaceCaptureFile = z.object({
+  path: z.string(),
+  status: GitFileStatusCode,
+  // sha256 of the captured after-image bytes; null when deleted / tooLarge.
+  hash: z.string().nullable(),
+  // git blob sha of the HEAD version — the wake-on-edit flush guard (dossier
+  // §10.1). null when the path is new/untracked (no HEAD blob).
+  baseHash: z.string().nullable(),
+  // Content-addressed storage key of the after-image; null when deleted /
+  // tooLarge / binary (no inline content captured).
+  contentRef: z.string().nullable(),
+  sizeBytes: z.number().int().nonnegative(),
+  isBinary: z.boolean().default(false),
+  // >5MB per-file content guard tripped: content NOT captured, render "open live".
+  tooLarge: z.boolean().default(false),
+  deleted: z.boolean().default(false)
+});
+var WorkspaceCaptureRepo = z.object({
+  root: z.string(),
+  head: z.string().nullable(),
+  detached: z.boolean().default(false),
+  upstream: z.string().nullable(),
+  ahead: z.number().int().nonnegative().default(0),
+  behind: z.number().int().nonnegative().default(0),
+  status: z.array(GitFileStatus),
+  diff: z.array(GitFileDiff)
+});
+var WorkspaceCaptureDegradedReason = z.enum([
+  "repository_discovery_command_failed",
+  "repository_discovery_timed_out",
+  "repository_discovery_result_limit_exceeded"
+]);
+var WorkspaceCaptureStats = z.object({
+  repoCount: z.number().int().nonnegative(),
+  fileCount: z.number().int().nonnegative(),
+  additions: z.number().int().nonnegative(),
+  deletions: z.number().int().nonnegative(),
+  totalBytes: z.number().int().nonnegative(),
+  tooLargeCount: z.number().int().nonnegative(),
+  binaryCount: z.number().int().nonnegative(),
+  treeEntryCount: z.number().int().nonnegative(),
+  treeTruncated: z.boolean().default(false),
+  durationMs: z.number().int().nonnegative(),
+  // sha256 over the change surface (per-file path/hash/status + per-repo diff
+  // summary, tree/mtime excluded). The empty-turn gate skips a capture whose
+  // fingerprint equals the previous revision's — "no new revision when nothing
+  // changed" holds even when the tree stays dirty across read-only turns.
+  fingerprint: z.string().optional()
+});
+var WorkspaceCaptureManifest = z.object({
+  version: z.literal(1),
+  revision: z.number().int().nonnegative(),
+  capturedAt: z.string(),
+  turnId: z.string().nullable(),
+  leaseEpoch: z.number().int().nonnegative(),
+  treeIndex: FsTreeNode,
+  treeTruncated: z.boolean().default(false),
+  repos: z.array(WorkspaceCaptureRepo),
+  files: z.array(WorkspaceCaptureFile),
+  stats: WorkspaceCaptureStats
+});
+var WorkspaceRevisionCapturedPayload = z.object({
+  revision: z.number().int().nonnegative(),
+  turnId: z.string().nullable(),
+  capturedAt: z.string(),
+  leaseEpoch: z.number().int().nonnegative(),
+  stats: WorkspaceCaptureStats
+});
+var WorkspaceRevisionDegradedPayload = z.object({
+  revision: z.number().int().nonnegative(),
+  turnId: z.string().nullable(),
+  capturedAt: z.string(),
+  leaseEpoch: z.number().int().nonnegative(),
+  reason: WorkspaceCaptureDegradedReason
+});
+var WorkspaceCaptureSignedUrl = z.object({
+  url: z.string().url(),
+  expiresAt: z.string()
+});
+var GetWorkspaceCaptureResponse = z.discriminatedUnion("available", [
+  z.object({
+    available: z.literal(false),
+    // Optional for additive compatibility with older servers. New servers set
+    // these fields when the newest durable revision is an explicit degraded
+    // marker rather than "no capture exists yet".
+    degradedReason: WorkspaceCaptureDegradedReason.nullable().optional(),
+    revision: z.number().int().nonnegative().nullable().optional(),
+    capturedAt: z.string().nullable().optional(),
+    turnId: z.string().nullable().optional(),
+    leaseEpoch: z.number().int().nonnegative().nullable().optional()
+  }),
+  z.object({
+    available: z.literal(true),
+    revision: z.number().int().nonnegative(),
+    capturedAt: z.string(),
+    turnId: z.string().nullable(),
+    leaseEpoch: z.number().int().nonnegative(),
+    sizeBytes: z.number().int().nonnegative(),
+    stats: WorkspaceCaptureStats,
+    manifest: WorkspaceCaptureManifest.nullable().default(null),
+    manifestUrl: WorkspaceCaptureSignedUrl.nullable().default(null)
+  })
+]);
+var GetWorkspaceCaptureFileResponse = z.object({
+  path: z.string(),
+  revision: z.number().int().nonnegative(),
+  status: GitFileStatusCode,
+  hash: z.string().nullable(),
+  baseHash: z.string().nullable(),
+  sizeBytes: z.number().int().nonnegative(),
+  isBinary: z.boolean(),
+  tooLarge: z.boolean(),
+  encoding: FsEncoding.nullable().default(null),
+  // set iff content is inline
+  content: z.string().nullable().default(null),
+  // inline ≤256KB (per encoding)
+  contentUrl: WorkspaceCaptureSignedUrl.nullable().default(null)
+  // signed >256KB
+});
 var GitLogRequest = z.object({
   path: z.string().default(""),
   ref: z.string().default("HEAD"),
@@ -2018,7 +2930,12 @@ var GitShowResponse = z.object({
   // null when fetching a raw blob
   files: z.array(GitFileDiff),
   // commit diff vs first parent
-  blob: z.object({ content: z.string(), encoding: FsEncoding, sizeBytes: z.number().int(), truncated: z.boolean() }).nullable(),
+  blob: z.object({
+    content: z.string(),
+    encoding: FsEncoding,
+    sizeBytes: z.number().int(),
+    truncated: z.boolean()
+  }).nullable(),
   revision: z.number().int().nonnegative()
 });
 var TerminalExecRequest = z.object({
@@ -2056,7 +2973,11 @@ var PtyOpenResponse = z.object({
   // false on backends without writeStdin
 });
 var PtyWriteRequest = z.object({ ptyId: z.string().uuid(), data: z.string() });
-var PtyResizeRequest = z.object({ ptyId: z.string().uuid(), cols: z.number().int().positive(), rows: z.number().int().positive() });
+var PtyResizeRequest = z.object({
+  ptyId: z.string().uuid(),
+  cols: z.number().int().positive(),
+  rows: z.number().int().positive()
+});
 var PtyCloseRequest = z.object({ ptyId: z.string().uuid() });
 var SessionStructuredCapabilities = z.object({
   FileSystem: z.object({ available: z.boolean(), readOnly: z.boolean(), root: z.string() }),
@@ -2079,9 +3000,31 @@ var SessionEvent = z.object({
   payload: z.unknown().default({}),
   occurredAt: z.string(),
   clientEventId: z.string().min(1).nullable().optional(),
-  turnId: z.string().uuid().nullable().optional()
-});
-var CreateSessionRequest = z.object({
+  turnId: z.string().uuid().nullable().optional(),
+  turnGeneration: z.number().int().nonnegative().nullable().optional(),
+  turnAttemptId: z.string().uuid().nullable().optional(),
+  turnAssociation: z.enum(["current", "late_rejected", "duplicate"]).nullable().optional(),
+  duplicateOfEventId: z.string().uuid().nullable().optional(),
+  duplicateReason: z.string().min(1).nullable().optional()
+});
+var SessionQueueMutationResponse = z.object({
+  snapshot: SessionQueueSnapshot,
+  events: z.array(SessionEvent),
+  shouldWake: z.boolean()
+});
+var SessionControlResponse = z.object({
+  operationId: z.string().uuid(),
+  event: SessionEvent,
+  controlState: SessionControlState,
+  controlGeneration: z.number().int().nonnegative(),
+  expectedActiveTurnId: z.string().uuid().nullable(),
+  expectedExecutionGeneration: z.number().int().nonnegative().nullable(),
+  expectedAttemptId: z.string().uuid().nullable(),
+  deliveryEventId: z.string().uuid().nullable(),
+  shouldSignalControl: z.boolean(),
+  shouldWake: z.boolean()
+});
+var CreateSessionRequest = withVariableSetIdAlias({
   initialMessage: z.string().min(1),
   // Per-session agent persona/system instructions (org-visible metadata, NOT a
   // secret). Rides the SAME system-level instructions channel the per-workspace
@@ -2090,7 +3033,7 @@ var CreateSessionRequest = z.object({
   // leaking them into the user-visible timeline (it is NEVER emitted as an
   // event, unlike goal/initialMessage). Trimmed, non-empty. The 32768-char cap
   // matches the codebase's largest free-form string convention (workspace
-  // environment variable values). Absent ⇒ byte-identical to today.
+  // variable set variable values). Absent ⇒ byte-identical to today.
   instructions: z.string().trim().min(1).max(32768).optional(),
   resources: z.array(ResourceRef).default([]),
   tools: z.array(ToolRef).default([]),
@@ -2109,9 +3052,15 @@ var CreateSessionRequest = z.object({
   // (the agent's resolve_cwd handles both). Only valid WITH targetSandboxId
   // (workingDir alone is a 422); omitted ⇒ the machine's default workspace_root.
   workingDir: z.string().min(1).optional(),
-  // Workspace environment attachment is fixed at session creation; follow-up
+  // Variable set attachment is fixed at session creation; follow-up
   // user.message events cannot switch or add one.
+  variableSetId: z.string().uuid().optional(),
   environmentId: z.string().uuid().optional(),
+  // The rig to bind this session to (M3). Its ACTIVE version is resolved and
+  // FROZEN onto the session at create. Omitted ⇒ the workspace's default rig
+  // (workspaces.default_rig_id) when set, else a rig-less session (today's
+  // behavior). An id that does not name a rig in the workspace is a 422.
+  rigId: z.string().uuid().optional(),
   goal: GoalSpec.optional(),
   clientEventId: z.string().min(1).optional(),
   // Workspace-scoped CREATE idempotency key: collapses concurrent/retried
@@ -2123,7 +3072,7 @@ var CreateSessionRequest = z.object({
   idempotencyKey: z.string().min(1).max(200).optional(),
   // Permissions the session's first-party MCP token should carry instead of
   // the fixed worker default — how an operator hands a manager-style session
-  // the orchestration/environment/github tools. Capped at creation: every
+  // the orchestration/variableSet/github tools. Capped at creation: every
   // requested permission must be held by the creating grant (no escalation).
   firstPartyMcpPermissions: z.array(Permission).optional(),
   // Third-party MCP servers attached only to this session. Credential headers are
@@ -2141,16 +3090,12 @@ var CreateSessionRequest = z.object({
   // A shared spawn inherits the box's (backend, os) — it is literally the same
   // box; the child cannot pick its own backend. Cross-workspace sharing is
   // forbidden by construction (the parent/group reads are RLS-workspace-scoped).
-  // ENV-AWARE: the box's environment is fixed at creation, so a share requires
-  // the SAME environmentId as the creator's box. On a mismatch the inherited
+  // ENV-AWARE: the box's variable set is fixed at creation, so a share requires
+  // the SAME variableSetId as the creator's box. On a mismatch the inherited
   // default silently falls back to an own box; an explicit "shared"/{groupId}
   // request 422s at create (instead of the first turn dying on the SDK's
   // manifest-env guard).
-  sandbox: z.union([
-    z.literal("shared"),
-    z.literal("new"),
-    z.object({ groupId: z.string().uuid() })
-  ]).optional()
+  sandbox: z.union([z.literal("shared"), z.literal("new"), z.object({ groupId: z.string().uuid() })]).optional()
 });
 var ClientSessionEvent = z.discriminatedUnion("type", [
   z.object({
@@ -2167,11 +3112,6 @@ var ClientSessionEvent = z.discriminatedUnion("type", [
       mcpCredentialUpdates: z.array(SessionMcpCredentialUpdateInput).optional()
     })
   }),
-  z.object({
-    type: z.literal("user.interrupt"),
-    clientEventId: z.string().min(1).optional(),
-    payload: z.object({ reason: z.string().optional() }).default({})
-  }),
   z.object({
     type: z.literal("user.approvalDecision"),
     clientEventId: z.string().min(1).optional(),
@@ -2182,6 +3122,21 @@ var ClientSessionEvent = z.discriminatedUnion("type", [
     })
   })
 ]);
+var SteerSessionMessageRequest = z.object({
+  text: z.string().min(1),
+  resources: z.array(ResourceRef).default([]),
+  tools: z.array(ToolRef).default([]),
+  model: z.string().min(1).optional(),
+  reasoningEffort: ReasoningEffort.optional(),
+  clientEventId: z.string().min(1).optional(),
+  expectedControlGeneration: z.number().int().nonnegative().optional(),
+  expectedWorkspaceInferenceGeneration: z.number().int().nonnegative().optional(),
+  mcpCredentialUpdates: z.array(SessionMcpCredentialUpdateInput).optional()
+});
+var SteerSessionMessageResponse = z.object({
+  accepted: SessionEvent,
+  turn: SessionTurn
+});
 var SessionBusMessage = z.object({
   workspaceId: z.string().uuid(),
   sessionId: z.string().uuid(),
@@ -2400,7 +3355,13 @@ var DeviceEnrollmentApproveResponse = z.object({
 var DeviceEnrollmentPollRequest = z.object({
   deviceCode: z.string().min(1).max(256)
 });
-var DeviceEnrollmentState = z.enum(["pending", "authorized", "denied", "expired", "disabled"]);
+var DeviceEnrollmentState = z.enum([
+  "pending",
+  "authorized",
+  "denied",
+  "expired",
+  "disabled"
+]);
 var EnrollmentCredentialsResponse = z.object({
   agentId: z.string().uuid(),
   workspaceId: z.string().uuid(),
@@ -2441,6 +3402,11 @@ var EnrollmentSummary = z.object({
   pubkey: z.string(),
   exposure: z.literal("whole-machine"),
   hasDisplay: z.boolean(),
+  // Present (non-null) only when a display EXISTS but capture is blocked (macOS
+  // Screen Recording / TCC not granted): a human, actionable reason so the UI can
+  // show "display: capture not granted" instead of a bare "headless". null == capture
+  // permitted OR genuinely headless.
+  desktopUnavailableReason: z.string().nullish(),
   allowScreenControl: z.boolean(),
   status: z.enum(["active", "revoked"]),
   os: EnrollmentOs,
@@ -2537,6 +3503,10 @@ var MachineView = z.object({
   os: z.string(),
   arch: z.string(),
   hasDisplay: z.boolean(),
+  // Non-null only when a display exists but capture is blocked (macOS Screen
+  // Recording / TCC not granted) — the UI can surface "display: capture not granted".
+  // null == capture permitted OR headless.
+  desktopUnavailableReason: z.string().nullish(),
   allowScreenControl: z.boolean(),
   sharedSessionCount: z.number().int(),
   lastSeenAt: z.string().nullable(),
@@ -2554,7 +3524,18 @@ var SwapActiveSandboxResponse = z.object({
   swapped: z.boolean(),
   activeSandboxId: z.string().nullable(),
   activeEpoch: z.number().int(),
-  reason: z.string().optional()
+  reason: z.string().optional(),
+  // Typed rejection discriminant (issue #341). Present only when swapped is false,
+  // so a client distinguishes a deleted/absent target from an unaddressable
+  // enrollment from a backend the turn cannot establish from a lost epoch race —
+  // without parsing the human reason string.
+  code: z.enum([
+    "stale_pointer",
+    "offline_enrollment",
+    "unsupported_backend_context",
+    "transient_establishment",
+    "concurrent_swap"
+  ]).optional()
 });
 var MachineMetricsSeriesResponse = z.object({
   samples: z.array(MetricSample)
@@ -2581,10 +3562,12 @@ var ClientConfig = z.object({
   models: z.array(ClientModel).default([]),
   defaultReasoningEffort: ReasoningEffort,
   allowedReasoningEfforts: z.array(ReasoningEffort).min(1),
-  mcpServers: z.array(z.object({
-    id: z.string(),
-    name: z.string()
-  })).default([]),
+  mcpServers: z.array(
+    z.object({
+      id: z.string(),
+      name: z.string()
+    })
+  ).default([]),
   fileUploads: z.object({
     enabled: z.boolean(),
     maxSizeBytes: z.number().int().positive()
@@ -2630,6 +3613,18 @@ function constantTimeEqual(actual, expected) {
   }
   return diff === 0;
 }
+function evaluateWorkspaceModelPolicy(policy, candidate) {
+  if (!policy) {
+    return { allowed: true };
+  }
+  if (policy.allowedProviders !== null && !policy.allowedProviders.includes(candidate.providerId)) {
+    return { allowed: false, reason: "provider" };
+  }
+  if (policy.allowedModels !== null && !policy.allowedModels.includes(candidate.modelId)) {
+    return { allowed: false, reason: "model" };
+  }
+  return { allowed: true };
+}
 export {
   AccessContext,
   AccessGrant,
@@ -2646,8 +3641,11 @@ export {
   CAPABILITY_DESCRIPTORS,
   CLEARED_RUN_STATE_BLOB,
   CLEARED_RUN_STATE_MARKER,
+  CancelSessionQueueItemRequest,
+  CapabilityCatalogAuthKind,
   CapabilityCatalogItem,
   CapabilityCatalogResponse,
+  CapabilityCatalogTier,
   CapabilityInstallation,
   CapabilityInstallationStatus,
   CapabilityKind,
@@ -2669,18 +3667,27 @@ export {
   CompactSessionContextRequest,
   CompactSessionContextResult,
   CompleteFileUploadResponse,
+  ConnectionCredentialBundle,
+  ConnectionKind,
+  ConnectionMetadata,
+  ConnectionResponse,
+  ConnectionStatus,
   CreateApiKeyRequest,
   CreateApiKeyResponse,
   CreateCapabilityCatalogItemRequest,
   CreateCheckoutRequest,
   CreateCheckoutResponse,
+  CreateConnectionRequest,
   CreateDocumentBaseRequest,
   CreateFileUploadRequest,
   CreateFileUploadResponse,
+  CreateKnowledgeMemoryRequest,
+  CreateRigRequest,
   CreateScheduledTaskRequest,
   CreateSessionRequest,
   CreateSocialConnectionRequest,
   CreateSocialPostRequest,
+  CreateVariableSetRequest,
   CreateWorkspaceEnvironmentRequest,
   CreateWorkspaceRequest,
   DESKTOP_STREAM_PORT,
@@ -2700,6 +3707,7 @@ export {
   DiscoverMcpCapabilitiesResponse,
   Document,
   DocumentBase,
+  DocumentSearchMode,
   DocumentSearchRequest,
   DocumentSearchResult,
   DocumentStatus,
@@ -2741,8 +3749,12 @@ export {
   FsTreeNode,
   FsWriteRequest,
   FsWriteResponse,
+  GetWorkspaceCaptureFileResponse,
+  GetWorkspaceCaptureResponse,
   GitChangedPayload,
   GitCommit,
+  GitCredentialProvider,
+  GitCredentialRepositoryRef,
   GitDiffHunk,
   GitDiffLine,
   GitDiffLineType,
@@ -2760,8 +3772,17 @@ export {
   GitStatusRequest,
   GitStatusResponse,
   GoalSpec,
+  IntegrationClientMetadata,
+  KnowledgeMemory,
+  KnowledgeMemoryKind,
+  KnowledgeMemorySearchRequest,
+  KnowledgeMemoryStatus,
+  KnowledgeSourceKind,
+  KnowledgeSourceRef,
   LimitAction,
   LimitDecision,
+  LineageNode,
+  ListConnectionsResponse,
   ListEnrollmentsResponse,
   ListWorkspaceMembersResponse,
   MachineKind,
@@ -2771,13 +3792,17 @@ export {
   MachinesResponse,
   ManagedAccount,
   MarketingDailyAnalysisTaskRequest,
+  McpServerConnectionRef,
   MetricSample,
   MintEnrollTokenRequest,
   MintEnrollTokenResponse,
+  OAuthStartRequest,
+  OAuthStartResponse,
   PackInstallation,
   PackInstallationStatus,
   Permission,
   ProductAccessMode,
+  ProposeRigChangeRequest,
   PtyCloseRequest,
   PtyOpenRequest,
   PtyOpenResponse,
@@ -2793,11 +3818,21 @@ export {
   RecordingStartedPayload,
   RegisterCapabilityPackRequest,
   RelayTokenPayload,
-  ReorderSessionTurnsRequest,
   RepositoryResourceRef,
   ResourceRef,
   ResourceRefConflictError,
   RevokeEnrollmentResponse,
+  Rig,
+  RigChange,
+  RigChangeKind,
+  RigChangeStatus,
+  RigChangeVerification,
+  RigCheck,
+  RigCheckResult,
+  RigDefinitionEditPayload,
+  RigSetupAppendPayload,
+  RigVerificationHealth,
+  RigVersion,
   SandboxBackend,
   SandboxCapabilityName,
   SandboxCommandOutputDeltaPayload,
@@ -2814,26 +3849,40 @@ export {
   Session,
   SessionBusMessage,
   SessionCapabilities,
+  SessionControlRequest,
+  SessionControlResponse,
+  SessionControlState,
   SessionEvent,
   SessionEventType,
   SessionGoal,
   SessionGoalCreatedBy,
   SessionGoalPausedReason,
   SessionGoalStatus,
+  SessionLineageResponse,
+  SessionListResponse,
   SessionMcpCredentialUpdateInput,
   SessionMcpServerInput,
   SessionMcpServerMetadata,
+  SessionQueueMutationResponse,
+  SessionQueueSnapshot,
   SessionStatus,
   SessionStructuredCapabilities,
+  SessionSystemUpdate,
+  SessionSystemUpdateKind,
+  SessionSystemUpdateState,
   SessionTurn,
   SessionTurnSource,
   SessionTurnStatus,
+  SetVariableSetVariableRequest,
+  SetWorkspaceDefaultRigRequest,
   SetWorkspaceEnvironmentVariableRequest,
   SocialConnection,
   SocialConnectionStatus,
   SocialPost,
   SocialProvider,
   StaticUsageLimits,
+  SteerSessionMessageRequest,
+  SteerSessionMessageResponse,
   StreamClosedPayload,
   StreamOpenedPayload,
   StreamRevokedPayload,
@@ -2841,37 +3890,66 @@ export {
   StreamUrlRotatedPayload,
   SwapActiveSandboxRequest,
   SwapActiveSandboxResponse,
+  SystemUpdateClassification,
   TERMINAL_STREAM_PORT,
   TerminalExecRequest,
   TerminalExecResponse,
   TerminalPtyExitedPayload,
   TerminalPtyOutputDeltaPayload,
   TerminalPtyStartedPayload,
+  ToolAuthNeededPayload,
   ToolRef,
   TriggerScheduledTaskRequest,
+  UpdateConnectionRequest,
+  UpdateKnowledgeMemoryRequest,
+  UpdateRigRequest,
   UpdateScheduledTaskRequest,
   UpdateSessionGoalRequest,
+  UpdateSessionPinRequest,
   UpdateSessionRequest,
-  UpdateSessionTurnRequest,
+  UpdateVariableSetRequest,
   UpdateWorkspaceEnvironmentRequest,
   UpdateWorkspaceMemberRequest,
+  UpdateWorkspaceModelPolicyRequest,
   UpdateWorkspaceRequest,
+  UpdateWorkspaceSettingsRequest,
   UsageEvent,
   UsageEventType,
   UsageLimitsMode,
+  VariableSet,
+  VariableSetVariableMetadata,
+  VariableSetVariableName,
   ViewerHeartbeatRequest,
   ViewerHeartbeatResponse,
   ViewerHolder,
   Workspace,
+  WorkspaceCaptureDegradedReason,
+  WorkspaceCaptureFile,
+  WorkspaceCaptureManifest,
+  WorkspaceCaptureRepo,
+  WorkspaceCaptureSignedUrl,
+  WorkspaceCaptureStats,
   WorkspaceEnvironment,
   WorkspaceEnvironmentVariableMetadata,
-  WorkspaceEnvironmentVariableName,
+  WorkspaceInferenceControlRequest,
+  WorkspaceInferenceControlResponse,
+  WorkspaceInferenceState,
   WorkspaceMember,
+  WorkspaceMemorySearchMode,
+  WorkspaceMemorySearchRequest,
+  WorkspaceMemorySearchResponse,
+  WorkspaceMemorySearchResult,
   WorkspaceRegisteredPack,
+  WorkspaceRevisionCapturedPayload,
+  WorkspaceRevisionDegradedPayload,
+  WorkspaceSettingsSchema,
+  evaluateWorkspaceModelPolicy,
   isClearedRunStateBlob,
   mergeResourceRefs,
   mergeToolRefs,
+  prefixedMcpToolName,
   reasoningEffortForMetadata,
+  resolveWorkspaceMemoryEnabled,
   resourceIdentityKey,
   signDelegatedAccessToken,
   signEnrollToken,