@opengeni/contracts 0.44.1 → 1.0.1

package/src/index.ts

@@ -10,8 +10,10 @@ import { MemorySlackPublicationDistribution } from "./memory-slack-delivery";
 import { WorkspaceInstructionPolicyRoleKeyInput } from "./workspace-instruction-policies";
 import { ClientResumableVoiceInputConfig } from "./transcription-recordings";
 import { MediaGenerationResult } from "./video-generation";
+import { KnowledgeProviderCitation } from "./knowledge";
 
 export * from "./slack-bot-scopes";
+export * from "./slack-task-policy";
 export * from "./atlassian";
 export * from "./connector-destinations";
 export * from "./memory-slack-delivery";
@@ -245,7 +247,7 @@ export type CapabilityDescriptor = {
     FileSystem: { available: boolean; readOnly: boolean };
     Terminal: {
       available: boolean;
-      transport: "sse-events" | "pty-ws" | null;
+      transport: "sse-events" | "pty-ws" | "relay-pty" | null;
       pty: boolean;
     };
     Git: { available: boolean };
@@ -567,7 +569,7 @@ export const CAPABILITY_DESCRIPTORS: Record<SandboxBackend, CapabilityDescriptor
     os: { supported: ["linux", "macos", "windows"], default: "linux" },
     capabilities: {
       FileSystem: { available: true, readOnly: false },
-      Terminal: { available: true, transport: "pty-ws", pty: true }, // real PTY over the relay
+      Terminal: { available: true, transport: "relay-pty", pty: true }, // real PTY over the relay
       Git: { available: true },
       DesktopStream: { available: true, transport: "vnc-ws" }, // proclaimed; consent-gated at enroll
       Recording: { available: true }, // boot invariant: == DesktopStream.available
@@ -625,6 +627,7 @@ export const ErrorEnvelope = z.object({
     code: ErrorCode,
     message: z.string(),
     retryable: z.boolean(),
+    outcomeUnknown: z.boolean().optional(),
     requestId: z.string().optional(),
     details: z.record(z.string(), z.unknown()).optional(),
   }),
@@ -798,6 +801,7 @@ export const FIRST_PARTY_MCP_TOOL_NAMES = [
   "set_session_title",
   "goal_set",
   "goal_update",
+  "goal_progress",
   "goal_complete",
   "goal_pause",
   "memory_search",
@@ -805,6 +809,9 @@ export const FIRST_PARTY_MCP_TOOL_NAMES = [
   "memory_correct",
   "preference_registry_summary",
   "preference_registry_get",
+  "task_notes_list",
+  "task_note_save",
+  "task_note_archive",
   "sandboxes_list",
   "sandbox_attach",
   "sandbox_swap",
@@ -830,13 +837,17 @@ export const FIRST_PARTY_MCP_TOOL_NAMES = [
   "browser_tabs",
   "browser_observe",
   "browser_act",
+  "browser_clipboard",
   "browser_debug",
+  "browser_auth",
+  "interaction_request_human",
   "browser_identity",
   "browser_publish",
   "browser_lifecycle",
   "computer_open",
   "computer_targets",
   "computer_observe",
+  "computer_clipboard",
   "computer_act",
   "computer_lifecycle",
   "variable_set_list",
@@ -886,6 +897,16 @@ export const FIRST_PARTY_MCP_TOOL_NAMES = [
   "slack_bot_file_content",
   "slack_bot_post_message",
   "slack_bot_delete_message",
+  "fiken_companies_list",
+  "fiken_contacts_list",
+  "fiken_contact_create",
+  "fiken_products_list",
+  "fiken_invoices_list",
+  "fiken_invoice_get",
+  "fiken_invoice_draft_create",
+  "fiken_bank_accounts_list",
+  "fiken_purchases_list",
+  "fiken_sales_list",
   "atlassian_sources_list",
   "atlassian_search",
   "atlassian_get",
@@ -917,13 +938,17 @@ export const FIRST_PARTY_IN_PROCESS_TOOL_NAMES = [
   "browser_tabs",
   "browser_observe",
   "browser_act",
+  "browser_clipboard",
   "browser_debug",
+  "browser_auth",
+  "interaction_request_human",
   "browser_identity",
   "browser_publish",
   "browser_lifecycle",
   "computer_open",
   "computer_targets",
   "computer_observe",
+  "computer_clipboard",
   "computer_act",
   "computer_lifecycle",
 ] as const satisfies readonly FirstPartyMcpToolName[];
@@ -932,9 +957,27 @@ const FIRST_PARTY_IN_PROCESS_TOOL_NAME_SET = new Set<FirstPartyMcpToolName>(
   FIRST_PARTY_IN_PROCESS_TOOL_NAMES,
 );
 
+/**
+ * Names accepted for stored-selection compatibility but intentionally omitted
+ * from the remote first-party `opengeni` MCP server.
+ *
+ * `slack_bot_post_message` cannot accept a model/caller-supplied UUID as a
+ * trustworthy logical-delivery identity. Server-owned Slack delivery paths
+ * call the internal client directly with their own durable operation IDs.
+ */
+const FIRST_PARTY_COMPATIBILITY_ONLY_TOOL_NAMES = [
+  "slack_bot_post_message",
+] as const satisfies readonly FirstPartyMcpToolName[];
+
+const FIRST_PARTY_COMPATIBILITY_ONLY_TOOL_NAME_SET = new Set<FirstPartyMcpToolName>(
+  FIRST_PARTY_COMPATIBILITY_ONLY_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),
+  (name) =>
+    !FIRST_PARTY_IN_PROCESS_TOOL_NAME_SET.has(name) &&
+    !FIRST_PARTY_COMPATIBILITY_ONLY_TOOL_NAME_SET.has(name),
 ) satisfies readonly FirstPartyMcpToolName[];
 
 /** Authored CodeMode paths for the canonical collaborative artifact surface. */
@@ -960,6 +1003,7 @@ export const DEFAULT_FIRST_PARTY_MCP_TOOLS = FIRST_PARTY_MCP_TOOL_NAMES.filter(
     !name.startsWith("x_") &&
     !name.startsWith("reddit_") &&
     !name.startsWith("slack_bot_") &&
+    !name.startsWith("fiken_") &&
     !name.startsWith("atlassian_"),
 ) satisfies readonly FirstPartyMcpToolName[];
 
@@ -982,6 +1026,255 @@ export type UsageLimitsMode = z.infer<typeof UsageLimitsMode>;
 export const AccountRole = z.enum(["owner", "admin", "member"]);
 export type AccountRole = z.infer<typeof AccountRole>;
 
+/**
+ * Settled tenancy vocabulary for resources that may outlive or be used from
+ * more than one workspace. This names authority only; parsing one of these
+ * contracts never authorizes access by itself.
+ */
+export const ResourceAuthorityScope = z.enum(["organization", "workspace", "user"]);
+export type ResourceAuthorityScope = z.infer<typeof ResourceAuthorityScope>;
+
+export const ResourceAuthorityListScope = z.enum([
+  "effective",
+  "organization",
+  "workspace",
+  "user",
+]);
+export type ResourceAuthorityListScope = z.infer<typeof ResourceAuthorityListScope>;
+
+export const OrganizationMembershipStatus = z.enum([
+  "provisioning",
+  "active",
+  "suspended",
+  "revoked",
+]);
+export type OrganizationMembershipStatus = z.infer<typeof OrganizationMembershipStatus>;
+
+export const PersonalResourceRetentionMode = z.enum(["retain", "delete_after"]);
+export type PersonalResourceRetentionMode = z.infer<typeof PersonalResourceRetentionMode>;
+
+export const SessionTenancyVisibility = z.enum(["user_private", "workspace_shared"]);
+export type SessionTenancyVisibility = z.infer<typeof SessionTenancyVisibility>;
+
+/** Public/session API vocabulary. Persistence keeps the explicit tenancy names. */
+export const SessionVisibility = z.enum(["private", "workspace"]);
+export type SessionVisibility = z.infer<typeof SessionVisibility>;
+
+export function sessionVisibilityToPublic(value: SessionTenancyVisibility): SessionVisibility {
+  return value === "user_private" ? "private" : "workspace";
+}
+
+export function sessionVisibilityFromPublic(value: SessionVisibility): SessionTenancyVisibility {
+  return value === "private" ? "user_private" : "workspace_shared";
+}
+
+export const UserResourceGrantMode = z.enum(["once", "session", "always"]);
+export type UserResourceGrantMode = z.infer<typeof UserResourceGrantMode>;
+
+/** Canonical non-wildcard action named by a personal-resource grant. */
+export const UserResourceGrantAction = z
+  .string()
+  .min(1)
+  .max(64)
+  .regex(/^[a-z0-9](?:[a-z0-9._:-]*[a-z0-9])?$/u);
+export type UserResourceGrantAction = z.infer<typeof UserResourceGrantAction>;
+
+export const UserResourceGrantStatus = z.enum(["active", "consumed", "revoked", "expired"]);
+export type UserResourceGrantStatus = z.infer<typeof UserResourceGrantStatus>;
+
+function refineUserResourceGrantFence(
+  value: {
+    mode: UserResourceGrantMode;
+    sessionId: string | null;
+    authorityEpoch: number | null;
+  },
+  context: z.RefinementCtx,
+): void {
+  const sessionBoundMode = value.mode === "once" || value.mode === "session";
+  const hasSession = value.sessionId !== null;
+  const hasAuthorityEpoch = value.authorityEpoch !== null;
+
+  if (sessionBoundMode && !hasSession) {
+    context.addIssue({
+      code: "custom",
+      path: ["sessionId"],
+      message: "once and session grants require an exact sessionId",
+    });
+  }
+  if (sessionBoundMode && !hasAuthorityEpoch) {
+    context.addIssue({
+      code: "custom",
+      path: ["authorityEpoch"],
+      message: "once and session grants require an authorityEpoch fence",
+    });
+  }
+  if (!sessionBoundMode && (hasSession || hasAuthorityEpoch)) {
+    context.addIssue({
+      code: "custom",
+      path: ["mode"],
+      message: "always grants must not carry a session or authority-epoch fence",
+    });
+  }
+  if (hasSession !== hasAuthorityEpoch) {
+    context.addIssue({
+      code: "custom",
+      path: ["authorityEpoch"],
+      message: "sessionId and authorityEpoch must be present or absent together",
+    });
+  }
+}
+
+/** Self-only organization membership projection; no subject identifier leaks. */
+export const OrganizationMembershipProjection = z.object({
+  id: z.string().uuid(),
+  organizationId: z.string().uuid(),
+  status: OrganizationMembershipStatus,
+  personalWorkspaceId: z.string().uuid().nullable(),
+  personalRetentionUntil: z.string().datetime({ offset: true }).nullable(),
+});
+export type OrganizationMembershipProjection = z.infer<typeof OrganizationMembershipProjection>;
+
+/**
+ * Exact active-membership facts returned by managed-human login provisioning.
+ * Retention is intentionally absent because the narrow provisioning capability
+ * neither reads nor mutates offboarding policy.
+ */
+export const ManagedOrganizationMembershipProjection = z.object({
+  id: z.string().uuid(),
+  organizationId: z.string().uuid(),
+  status: z.literal("active"),
+  personalWorkspaceId: z.string().uuid(),
+});
+export type ManagedOrganizationMembershipProjection = z.infer<
+  typeof ManagedOrganizationMembershipProjection
+>;
+
+export const ListManagedOrganizationMembershipsResponse = z.object({
+  memberships: z.array(ManagedOrganizationMembershipProjection),
+});
+export type ListManagedOrganizationMembershipsResponse = z.infer<
+  typeof ListManagedOrganizationMembershipsResponse
+>;
+
+/**
+ * Opaque user-resource authority projection. Ownership is represented by the
+ * server-issued authority id, never a raw subject or membership id.
+ */
+export const UserResourceAuthorityProjection = z.object({
+  id: z.string().uuid(),
+  organizationId: z.string().uuid(),
+  scope: z.literal("user"),
+  resourceKind: z.string().min(1).max(64),
+  originWorkspaceId: z.string().uuid().nullable(),
+  generation: z.number().int().positive(),
+  status: z.enum(["active", "retained", "revoked"]),
+});
+export type UserResourceAuthorityProjection = z.infer<typeof UserResourceAuthorityProjection>;
+
+/**
+ * Opaque grant projection. A grant is still inert until a server-side access
+ * boundary proves the organization, owner, workspace, session context, and
+ * current authority epoch.
+ */
+export const UserResourceGrantProjection = z
+  .object({
+    id: z.string().uuid(),
+    authorityId: z.string().uuid(),
+    organizationId: z.string().uuid(),
+    workspaceId: z.string().uuid(),
+    sessionId: z.string().uuid().nullable(),
+    action: UserResourceGrantAction,
+    mode: UserResourceGrantMode,
+    context: SessionTenancyVisibility,
+    authorityEpoch: z.number().int().positive().nullable(),
+    generation: z.number().int().positive(),
+    status: UserResourceGrantStatus,
+    expiresAt: z.string().datetime({ offset: true }).nullable(),
+  })
+  .superRefine(refineUserResourceGrantFence);
+export type UserResourceGrantProjection = z.infer<typeof UserResourceGrantProjection>;
+
+/**
+ * Extensible immutable delegation payload for accepted work. It contains only
+ * opaque authority/grant identity and execution fences, never owner identity
+ * or credential material.
+ */
+export const UserResourceDelegation = z
+  .object({
+    authorityId: z.string().uuid(),
+    grantId: z.string().uuid(),
+    organizationId: z.string().uuid(),
+    workspaceId: z.string().uuid(),
+    sessionId: z.string().uuid().nullable(),
+    action: UserResourceGrantAction,
+    mode: UserResourceGrantMode,
+    context: SessionTenancyVisibility,
+    authorityEpoch: z.number().int().positive().nullable(),
+    authorityGeneration: z.number().int().positive(),
+    grantGeneration: z.number().int().positive(),
+    resourceVersionId: z.string().uuid().nullable().optional(),
+  })
+  .superRefine(refineUserResourceGrantFence);
+export type UserResourceDelegation = z.infer<typeof UserResourceDelegation>;
+
+/**
+ * Compatibility envelope for future resource selectors. Omitted scope and
+ * authority parse to workspace-only behavior; user authority is impossible
+ * without one complete opaque delegation.
+ */
+export const ResourceAuthorityEnvelope = z
+  .object({
+    scope: ResourceAuthorityScope.default("workspace"),
+    userDelegation: UserResourceDelegation.optional(),
+  })
+  .superRefine((value, context) => {
+    if (value.scope === "user" && value.userDelegation === undefined) {
+      context.addIssue({
+        code: "custom",
+        path: ["userDelegation"],
+        message: "user scope requires an explicit immutable delegation",
+      });
+    }
+    if (value.scope !== "user" && value.userDelegation !== undefined) {
+      context.addIssue({
+        code: "custom",
+        path: ["userDelegation"],
+        message: "only user scope may carry a user delegation",
+      });
+    }
+  });
+export type ResourceAuthorityEnvelope = z.infer<typeof ResourceAuthorityEnvelope>;
+
+/** Secret-safe generic session tenancy metadata for an authorized viewer. */
+export const SessionTenancyProjection = z.object({
+  visibility: SessionTenancyVisibility,
+  authorityEpoch: z.number().int().positive(),
+  ownedByCurrentUser: z.boolean(),
+  fork: z
+    .object({
+      sourceVisibility: SessionTenancyVisibility,
+      sourceAuthorityEpoch: z.number().int().positive(),
+      forkedAt: z.string().datetime({ offset: true }),
+    })
+    .nullable(),
+});
+export type SessionTenancyProjection = z.infer<typeof SessionTenancyProjection>;
+
+/** Secret-safe public projection used by activated session APIs. */
+export const SessionTenancyPublicProjection = z.object({
+  visibility: SessionVisibility,
+  authorityEpoch: z.number().int().positive(),
+  ownedByCurrentUser: z.boolean(),
+  fork: z
+    .object({
+      sourceVisibility: SessionVisibility,
+      sourceAuthorityEpoch: z.number().int().positive(),
+      forkedAt: z.string().datetime({ offset: true }),
+    })
+    .nullable(),
+});
+export type SessionTenancyPublicProjection = z.infer<typeof SessionTenancyPublicProjection>;
+
 export const ManagedAccount = z.object({
   id: z.string().uuid(),
   name: z.string(),
@@ -1422,12 +1715,17 @@ export const DEFAULT_WORKSPACE_SLACK_REACTION_SUMMON_SETTINGS = {
   channelPolicy: { mode: "bot_member" },
 } as const satisfies WorkspaceSlackReactionSummonSettings;
 
+export const WorkspaceMemoryPromptMode = z.enum(["legacy_standing", "retrieval_only"]);
+export type WorkspaceMemoryPromptMode = z.infer<typeof WorkspaceMemoryPromptMode>;
+
 // Validates the KNOWN keys of workspaces.settings; passthrough keeps unknown
-// (future) keys rather than stripping them. memoryEnabled defaults off;
+// (future) keys rather than stripping them. memoryEnabled defaults off and the
+// reversible Memory V1 containment rollout defaults to legacy standing context;
 // voiceInput defaults to enabled when the deployment has a provider.
 export const WorkspaceSettingsSchema = z
   .object({
     memoryEnabled: z.boolean().optional(),
+    memoryPromptMode: WorkspaceMemoryPromptMode.optional(),
     /** Preferred workspace voice-input toggle. */
     voiceInput: WorkspaceVoiceInputSettings.optional(),
     /**
@@ -1457,6 +1755,12 @@ export function resolveWorkspaceMemoryEnabled(settings: unknown): boolean {
   return parsed.success ? parsed.data.memoryEnabled === true : false;
 }
 
+/** Reversible Memory V1 prompt rollout. Absent preserves legacy composition. */
+export function resolveWorkspaceMemoryPromptMode(settings: unknown): WorkspaceMemoryPromptMode {
+  const parsed = WorkspaceSettingsSchema.safeParse(settings ?? {});
+  return parsed.success ? (parsed.data.memoryPromptMode ?? "legacy_standing") : "legacy_standing";
+}
+
 /** Default Codex compaction mode for new Codex sessions (remote_v2 when unset). */
 export function resolveWorkspaceCodexCompactionDefault(settings: unknown): CodexCompactionMode {
   const parsed = WorkspaceSettingsSchema.safeParse(settings ?? {});
@@ -1527,6 +1831,7 @@ export function workspaceSlackReactionChannelAllowed(
 export const UpdateWorkspaceSettingsRequest = z
   .object({
     memoryEnabled: z.boolean().optional(),
+    memoryPromptMode: WorkspaceMemoryPromptMode.optional(),
     voiceInput: WorkspaceVoiceInputSettings.optional(),
     /** @deprecated Prefer `voiceInput`. Kept for one compatibility release. */
     transcription: WorkspaceTranscriptionPolicy.optional(),
@@ -1594,6 +1899,8 @@ const reservedServiceTurnInitiatorContextKeys = new Set([
   "backfill",
   "label",
   "provenanceError",
+  "opengeniSiteAuthConnectionId",
+  "opengeniSiteAuthMaintenanceOperationId",
   "via",
   "viaTruncated",
 ]);
@@ -1695,6 +2002,11 @@ export const DelegatedAccessTokenPayload = z
     // Model-visible first-party tool selection for a worker-bound session.
     // This is visibility only; permissions remain the authorization boundary.
     firstPartyMcpTools: z.array(FirstPartyMcpToolName).optional(),
+    // Trusted root-relative depth facts frozen when the worker prepares this
+    // attempt. They shape only the model-visible tool catalog; the database
+    // remains authoritative for admission and concurrent policy changes.
+    nestedAgentDepth: NestedAgentDepthValue.optional(),
+    effectiveMaxNestedAgentDepth: NestedAgentDepthValue.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
@@ -1715,6 +2027,23 @@ export const DelegatedAccessTokenPayload = z
       payload.executionGeneration,
     ];
     const exactAttemptClaimCount = exactAttemptClaims.filter((value) => value !== undefined).length;
+    const depthClaimCount = [payload.nestedAgentDepth, payload.effectiveMaxNestedAgentDepth].filter(
+      (value) => value !== undefined,
+    ).length;
+    if (depthClaimCount !== 0 && depthClaimCount !== 2) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["nestedAgentDepth"],
+        message: "nested-agent depth claims must be supplied together",
+      });
+    }
+    if (depthClaimCount > 0 && payload.principalKind !== "agent_attempt") {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["principalKind"],
+        message: "nested-agent depth claims require an agent_attempt principal",
+      });
+    }
     if (
       payload.principalKind === "human_session" &&
       (exactAttemptClaimCount !== 0 || payload.serviceInitiator !== undefined)
@@ -2371,9 +2700,9 @@ export type InsightsModelUsageRow = z.infer<typeof InsightsModelUsageRow>;
 
 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. */
+  /** UTC hour/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. */
+  /** UTC hour/day-bucketed hypothetical provider-rate USD for calls with captured pricing. */
   estimatedProviderUsd: z.number().nonnegative(),
   estimatedProviderCostKnownCalls: z.number().int().nonnegative(),
   warmSeconds: z.number().nonnegative(),
@@ -3697,6 +4026,7 @@ export const DocumentSearchResult = z.object({
   authorityKind: DocumentAuthorityKind,
   authorityWorkspaceId: z.string().uuid().nullable(),
   authoritySubjectId: z.string().nullable(),
+  citation: KnowledgeProviderCitation.nullable().optional(),
 });
 export type DocumentSearchResult = z.infer<typeof DocumentSearchResult>;
 
@@ -3726,6 +4056,7 @@ export const IndexedDocumentProvenance = z.object({
   authoritySubjectId: z.string().nullable(),
   createdBy: z.string().nullable(),
   createdAt: z.string(),
+  citation: KnowledgeProviderCitation.nullable().optional(),
 });
 export type IndexedDocumentProvenance = z.infer<typeof IndexedDocumentProvenance>;
 
@@ -4293,6 +4624,86 @@ export type SessionGoalStatus = z.infer<typeof SessionGoalStatus>;
 export const SessionGoalCreatedBy = z.enum(["api", "agent", "scheduled_task"]);
 export type SessionGoalCreatedBy = z.infer<typeof SessionGoalCreatedBy>;
 
+export const SessionGoalMutationPolicy = z.enum([
+  "review_changes",
+  "preserve_intent",
+  "autonomous_adaptation",
+]);
+export type SessionGoalMutationPolicy = z.infer<typeof SessionGoalMutationPolicy>;
+
+export const SessionGoalChangeKind = z.enum(["refinement", "adaptation", "replacement"]);
+export type SessionGoalChangeKind = z.infer<typeof SessionGoalChangeKind>;
+
+export const SESSION_GOAL_TEXT_MAX_BYTES = 8 * 1024;
+export const SESSION_GOAL_SUCCESS_CRITERIA_MAX_BYTES = 8 * 1024;
+export const SESSION_GOAL_RATIONALE_MAX_BYTES = 2 * 1024;
+export const SESSION_GOAL_PROGRESS_MAX_BYTES = 4 * 1024;
+
+export function sessionGoalUtf8Bytes(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}
+
+function boundedSessionGoalString(maxBytes: number, field: string) {
+  return z
+    .string()
+    .min(1)
+    .refine((value) => sessionGoalUtf8Bytes(value) <= maxBytes, {
+      message: `${field} exceeds ${maxBytes} UTF-8 bytes`,
+    });
+}
+
+const SessionGoalTextWrite = boundedSessionGoalString(SESSION_GOAL_TEXT_MAX_BYTES, "goal text");
+const SessionGoalSuccessCriteriaWrite = boundedSessionGoalString(
+  SESSION_GOAL_SUCCESS_CRITERIA_MAX_BYTES,
+  "goal success criteria",
+);
+const SessionGoalRationaleWrite = boundedSessionGoalString(
+  SESSION_GOAL_RATIONALE_MAX_BYTES,
+  "goal rationale",
+);
+
+export const SessionGoalSnapshot = z.discriminatedUnion("state", [
+  z.object({ state: z.literal("none"), capturedAt: z.string() }),
+  z.object({
+    state: z.enum(["active", "paused", "completed"]),
+    goalId: z.string().uuid(),
+    objectiveRevision: z.number().int().positive(),
+    text: SessionGoalTextWrite,
+    successCriteria: SessionGoalSuccessCriteriaWrite.nullable(),
+    mutationPolicy: SessionGoalMutationPolicy,
+    capturedAt: z.string(),
+  }),
+]);
+export type SessionGoalSnapshot = z.infer<typeof SessionGoalSnapshot>;
+
+export const SessionGoalRevision = z.object({
+  id: z.string().uuid(),
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  sessionId: z.string().uuid(),
+  goalId: z.string().uuid(),
+  disposition: z.enum(["applied", "proposed", "rejected"]),
+  changeKind: SessionGoalChangeKind,
+  baseObjectiveRevision: z.number().int().nonnegative(),
+  resultObjectiveRevision: z.number().int().positive().nullable(),
+  text: z.string().min(1),
+  successCriteria: z.string().nullable(),
+  mutationPolicy: SessionGoalMutationPolicy,
+  rationale: z.string().min(1),
+  actor: z.enum(["agent", "api", "scheduled_task"]),
+  actorTurnId: z.string().uuid().nullable(),
+  actorAttemptId: z.string().uuid().nullable(),
+  proposalId: z.string().uuid().nullable(),
+  createdAt: z.string(),
+});
+export type SessionGoalRevision = z.infer<typeof SessionGoalRevision>;
+
+export const ApplySessionGoalRevisionRequest = z.object({
+  expectedObjectiveRevision: z.number().int().positive(),
+  rationale: SessionGoalRationaleWrite.optional(),
+});
+export type ApplySessionGoalRevisionRequest = z.infer<typeof ApplySessionGoalRevisionRequest>;
+
 export const SessionGoalPausedReason = z.enum([
   "agent",
   "user_pause",
@@ -4351,6 +4762,8 @@ export const SessionGoal = z.object({
   pausedReason: z.string().nullable(),
   createdBy: SessionGoalCreatedBy,
   version: z.number().int().positive(),
+  objectiveRevision: z.number().int().positive(),
+  mutationPolicy: SessionGoalMutationPolicy,
   autoContinuations: z.number().int().nonnegative(),
   noProgressStreak: z.number().int().nonnegative(),
   maxAutoContinuations: z.number().int().positive().nullable(),
@@ -4364,16 +4777,26 @@ export const SessionGoal = z.object({
 export type SessionGoal = z.infer<typeof SessionGoal>;
 
 export const GoalSpec = z.object({
-  text: z.string().min(1),
-  successCriteria: z.string().min(1).optional(),
+  text: SessionGoalTextWrite,
+  successCriteria: SessionGoalSuccessCriteriaWrite.optional(),
   maxAutoContinuations: z.number().int().positive().optional(),
+  mutationPolicy: SessionGoalMutationPolicy.optional(),
 });
 export type GoalSpec = z.infer<typeof GoalSpec>;
 
-export const UpdateSessionGoalRequest = z.object({
-  status: z.enum(["paused", "active"]),
-  rationale: z.string().min(1).optional(),
-});
+export const UpdateSessionGoalRequest = z.union([
+  z.object({
+    status: z.enum(["paused", "active"]),
+    rationale: SessionGoalRationaleWrite.optional(),
+  }),
+  z.object({
+    text: SessionGoalTextWrite,
+    successCriteria: SessionGoalSuccessCriteriaWrite.nullable().optional(),
+    mutationPolicy: SessionGoalMutationPolicy.optional(),
+    rationale: SessionGoalRationaleWrite,
+    expectedObjectiveRevision: z.number().int().positive(),
+  }),
+]);
 export type UpdateSessionGoalRequest = z.infer<typeof UpdateSessionGoalRequest>;
 
 export const UpdateSessionRequest = z.object({
@@ -4669,8 +5092,26 @@ export const SessionRealtimeInboundEntry = z
     delegationItemId: z.string().max(1024).nullable().optional(),
     text: z.string().max(131_072).nullable().optional(),
     payload: z.record(z.string(), z.unknown()).optional(),
+    // Application context attached to the exact delegation/transcript message.
+    // It is ordinary model-visible user-message content when materialized, not
+    // a secret or instruction-authority boundary.
+    modelContext: z.string().trim().min(1).max(32768).optional(),
   })
-  .strict();
+  .strict()
+  .superRefine((entry, context) => {
+    if (
+      entry.modelContext !== undefined &&
+      entry.kind !== "delegation_call" &&
+      entry.kind !== "user_transcript" &&
+      entry.kind !== "assistant_transcript"
+    ) {
+      context.addIssue({
+        code: "custom",
+        path: ["modelContext"],
+        message: "modelContext requires a delegation or finalized transcript entry",
+      });
+    }
+  });
 export type SessionRealtimeInboundEntry = z.infer<typeof SessionRealtimeInboundEntry>;
 
 export const SyncSessionRealtimeLedgerRequest = SessionRealtimeOwnerProof.extend({
@@ -4702,6 +5143,7 @@ export type SyncSessionRealtimeLedgerResponse = z.infer<typeof SyncSessionRealti
 
 export const SessionRealtimeModel = z.enum([
   "gpt-live-1-boulder-alpha",
+  "supergrok/grok-voice-think-fast-2.0",
   "opengeni-gateway/openai/gpt-realtime-2.1",
   "opengeni-gateway/openai/gpt-realtime-mini",
   "opengeni-gateway/xai/grok-voice-think-fast-2.0",
@@ -4714,7 +5156,7 @@ export type SessionRealtimeModel = z.infer<typeof SessionRealtimeModel>;
 export const WorkspaceRealtimeModelCatalogItem = z.object({
   id: SessionRealtimeModel,
   label: z.string().min(1),
-  provider: z.enum(["OpenGeni", "Connected Codex", "Your Gateway"]),
+  provider: z.enum(["OpenGeni", "Connected Codex", "Connected SuperGrok", "Your Gateway"]),
   description: z.string().min(1),
   available: z.boolean(),
   unavailableReason: z.string().nullable(),
@@ -4808,11 +5250,14 @@ export const SessionAuthorizationOperation = z.enum([
   "session.human_input.read",
   "session.human_input.write",
   "session.title.write",
+  "session.channel.write",
   "session.mcp.approval_policy.write",
   "session.tool_policy.write",
   "session.goal.read",
   "session.goal.write",
   "session.child.create",
+  "session.visibility.write",
+  "session.fork.create",
 ]);
 export type SessionAuthorizationOperation = z.infer<typeof SessionAuthorizationOperation>;
 
@@ -5135,6 +5580,28 @@ export function renderTimelineAnnotationsForModel(
   ].join("\n");
 }
 
+export const MODEL_CONTEXT_LABEL = "[Application context attached to this user message]" as const;
+
+/**
+ * Build one canonical user-role message body. `modelContext` is ordinary
+ * message content: it is model-visible in the same chronological position as
+ * the visible text, but presentation layers may omit it. It is not a secret or
+ * an instruction-authority boundary.
+ */
+export function renderUserMessageContentForModel(
+  text: string,
+  annotations: readonly TimelineAnnotation[],
+  modelContext?: string | null,
+): string | Array<{ type: "input_text"; text: string }> {
+  const visibleContent = renderTimelineAnnotationsForModel(text, annotations);
+  const context = modelContext?.trim();
+  if (!context) return visibleContent;
+  return [
+    { type: "input_text", text: `${MODEL_CONTEXT_LABEL}\n${context}` },
+    { type: "input_text", text: visibleContent },
+  ];
+}
+
 export const SessionTurn = z
   .object({
     id: z.string().uuid(),
@@ -5744,12 +6211,16 @@ export const VariableSetVariableName = z
   .max(128);
 export type VariableSetVariableName = z.infer<typeof VariableSetVariableName>;
 
-function withVariableSetIdAlias<T extends z.ZodRawShape>(shape: T) {
+function withVariableSetIdAlias<T extends z.ZodRawShape>(
+  shape: T,
+  options: { rejectKeys?: readonly string[] } = {},
+) {
   return z.preprocess((input) => {
     if (!input || typeof input !== "object" || Array.isArray(input)) {
       return input;
     }
     const record = input as Record<string, unknown>;
+    if (options.rejectKeys?.some((key) => Object.hasOwn(record, key))) return null;
     if (record.variableSetId !== undefined || record.environmentId === undefined) {
       return record;
     }
@@ -6070,6 +6541,40 @@ export const UpdateRigRequest = z.object({
 });
 export type UpdateRigRequest = z.infer<typeof UpdateRigRequest>;
 
+// Workspace-shared channels organize root sessions ("workstreams") by work
+// type in the rail. Pure organizational metadata: filing a session into a
+// channel never affects execution, authority, memory, or history.
+export const Channel = 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(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type Channel = z.infer<typeof Channel>;
+
+export const CreateChannelRequest = z.object({
+  name: z.string().trim().min(1).max(80),
+  description: z.string().max(2000).optional(),
+});
+export type CreateChannelRequest = z.infer<typeof CreateChannelRequest>;
+
+export const UpdateChannelRequest = z.object({
+  name: z.string().trim().min(1).max(80).optional(),
+  description: z.string().max(2000).nullable().optional(),
+});
+export type UpdateChannelRequest = z.infer<typeof UpdateChannelRequest>;
+
+// Re-files one session (rail organization only). null moves it back to the
+// unfiled inbox.
+export const UpdateSessionChannelRequest = z.object({
+  channelId: z.string().uuid().nullable(),
+});
+export type UpdateSessionChannelRequest = z.infer<typeof UpdateSessionChannelRequest>;
+
 // setup_append: the exact command that already worked (+ an optional note).
 export const RigSetupAppendPayload = z.object({
   command: z.string().min(1).max(8192),
@@ -6418,47 +6923,48 @@ export const CreateScheduledTaskRequest = /* @__PURE__ */ z.union([
 ]);
 export type CreateScheduledTaskRequest = z.infer<typeof CreateScheduledTaskRequest>;
 
-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(),
-  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(),
-}).superRefine((value, context) => {
-  if (value.targetSessionId && value.runMode && value.runMode !== "existing_session") {
-    context.addIssue({
-      code: "custom",
-      path: ["targetSessionId"],
-      message: "targetSessionId requires runMode=existing_session",
-    });
-  }
-  if (value.runMode === "existing_session" && value.targetSessionId === null) {
-    context.addIssue({
-      code: "custom",
-      path: ["targetSessionId"],
-      message: "targetSessionId cannot be null when runMode=existing_session",
-    });
-  }
-  if (
-    value.agentConfig?.goal &&
-    (value.runMode === "existing_session" || Boolean(value.targetSessionId))
-  ) {
-    context.addIssue({
-      code: "custom",
-      path: ["agentConfig", "goal"],
-      message: "agentConfig.goal cannot be used with an existing-session target",
-    });
-  }
-});
+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(),
+    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(),
+  }).superRefine((value, context) => {
+    if (value.targetSessionId && value.runMode && value.runMode !== "existing_session") {
+      context.addIssue({
+        code: "custom",
+        path: ["targetSessionId"],
+        message: "targetSessionId requires runMode=existing_session",
+      });
+    }
+    if (value.runMode === "existing_session" && value.targetSessionId === null) {
+      context.addIssue({
+        code: "custom",
+        path: ["targetSessionId"],
+        message: "targetSessionId cannot be null when runMode=existing_session",
+      });
+    }
+    if (
+      value.agentConfig?.goal &&
+      (value.runMode === "existing_session" || Boolean(value.targetSessionId))
+    ) {
+      context.addIssue({
+        code: "custom",
+        path: ["agentConfig", "goal"],
+        message: "agentConfig.goal cannot be used with an existing-session target",
+      });
+    }
+  });
 export type UpdateScheduledTaskRequest = z.infer<typeof UpdateScheduledTaskRequest>;
 
 /**
@@ -6668,10 +7174,10 @@ export const CapabilityPackComponentReference = z.discriminatedUnion("kind", [
   z
     .object({
       key: CapabilityPackComponentKey,
-      kind: z.literal("feature"),
+      kind: z.literal("facet"),
       capabilityId: z.string().min(1).max(512),
       instanceKey: CapabilityPackInstanceKey,
-      featureKey: z.string().min(1).max(200),
+      facetKey: z.string().min(1).max(200),
       bindingKey: CapabilityPackInstanceKey,
       configDigest: z.string().regex(/^[0-9a-f]{64}$/),
       required: z.boolean().default(true),
@@ -6880,7 +7386,7 @@ export type PackComponentResolutionStatus = z.infer<typeof PackComponentResoluti
 export const PackComponentResolution = z
   .object({
     key: CapabilityPackComponentKey,
-    kind: z.enum(["plugin", "skill", "integration", "feature", "inline_skill"]),
+    kind: z.enum(["plugin", "skill", "integration", "facet", "inline_skill"]),
     capabilityId: z.string().min(1).max(512),
     required: z.boolean(),
     status: PackComponentResolutionStatus,
@@ -6956,7 +7462,7 @@ export const PackUninstallPreview = z
         z
           .object({
             key: CapabilityPackComponentKey,
-            kind: z.enum(["plugin", "skill", "integration", "feature", "inline_skill"]),
+            kind: z.enum(["plugin", "skill", "integration", "facet", "inline_skill"]),
             capabilityId: z.string().min(1).max(512),
             retainedByOtherOwners: z.boolean(),
           })
@@ -7102,6 +7608,48 @@ export const OpenGeniSlackBotConnectionMetadata = z
   .passthrough();
 export type OpenGeniSlackBotConnectionMetadata = z.infer<typeof OpenGeniSlackBotConnectionMetadata>;
 
+export const FIKEN_PROVIDER_DOMAIN = "fiken.no" as const;
+export const FIKEN_CREDENTIAL_ROLE = "fiken_api_token" as const;
+export const FIKEN_CREDENTIAL_LABEL = "Fiken API token" as const;
+
+export const FikenCompanySummary = z.object({
+  slug: z.string().min(1).max(128),
+  name: z.string().min(1).max(256),
+  organizationNumber: z.string().max(64).nullable(),
+});
+export type FikenCompanySummary = z.infer<typeof FikenCompanySummary>;
+
+export const FikenConnectionMetadata = z
+  .object({
+    credentialRole: z.literal(FIKEN_CREDENTIAL_ROLE),
+    credentialLabel: z.literal(FIKEN_CREDENTIAL_LABEL),
+    companies: z.array(FikenCompanySummary).max(100),
+    defaultCompanySlug: z.string().min(1).max(128).nullable(),
+    verifiedAt: z.string().datetime({ offset: true }),
+  })
+  .passthrough();
+export type FikenConnectionMetadata = z.infer<typeof FikenConnectionMetadata>;
+
+export const FikenInstallRequest = z.object({
+  apiToken: z.string().min(16).max(512),
+  defaultCompanySlug: z.string().min(1).max(128).optional(),
+  /** Existing Fiken connection to rewrite in place (reconnect). */
+  connectionId: z.string().uuid().optional(),
+});
+export type FikenInstallRequest = z.infer<typeof FikenInstallRequest>;
+
+export const FikenOAuthStartRequest = z.object({
+  /** Existing Fiken connection to re-authorize in place (reconnect). */
+  connectionId: z.string().uuid().optional(),
+});
+export type FikenOAuthStartRequest = z.infer<typeof FikenOAuthStartRequest>;
+
+export const FikenOAuthStartResponse = z.object({
+  authorizationUrl: z.string().url(),
+  expiresAt: z.string().datetime({ offset: true }),
+});
+export type FikenOAuthStartResponse = z.infer<typeof FikenOAuthStartResponse>;
+
 export const ConnectionMetadata = z.object({
   id: z.string().uuid(),
   accountId: z.string().uuid(),
@@ -7514,7 +8062,7 @@ export type CapabilityInstallation = z.infer<typeof CapabilityInstallation>;
 
 export const CreateCapabilityCatalogItemRequest = z.object({
   id: z.string().min(1).optional(),
-  kind: CapabilityKind.exclude(["pack"]),
+  kind: z.literal("mcp"),
   source: CapabilitySource.default("manual"),
   name: z.string().min(1),
   description: z.string().min(1).optional(),
@@ -7528,7 +8076,7 @@ export const CreateCapabilityCatalogItemRequest = z.object({
 });
 export type CreateCapabilityCatalogItemRequest = z.infer<typeof CreateCapabilityCatalogItemRequest>;
 
-export const EnableCapabilityRequest = withVariableSetIdAlias({
+export const EnableCapabilityRequest = z.object({
   config: z.record(z.string(), z.unknown()).default({}),
   metadata: z.record(z.string(), z.unknown()).default({}),
   connectionRef: McpServerConnectionRef.optional(),
@@ -7539,14 +8087,6 @@ export const EnableCapabilityRequest = withVariableSetIdAlias({
    * 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>;
 
@@ -7566,6 +8106,9 @@ export type DiscoverMcpCapabilitiesResponse = z.infer<typeof DiscoverMcpCapabili
 export const SkillImportSource = z.enum(["github", "skills_sh"]);
 export type SkillImportSource = z.infer<typeof SkillImportSource>;
 
+export const SkillInstallationSource = z.enum(["library", "github", "skills_sh", "pack"]);
+export type SkillInstallationSource = z.infer<typeof SkillInstallationSource>;
+
 export const PreviewSkillImportRequest = z.object({
   url: z.string().url().max(2048),
 });
@@ -7605,6 +8148,15 @@ export const InstallSkillRequest = z.object({
 });
 export type InstallSkillRequest = z.infer<typeof InstallSkillRequest>;
 
+export const InstallLibrarySkillRequest = z
+  .object({
+    expectedVersion: z.string().min(1).max(96),
+    expectedContentSha256: z.string().regex(/^[0-9a-f]{64}$/),
+    expectedInstallationVersion: z.number().int().positive().optional(),
+  })
+  .strict();
+export type InstallLibrarySkillRequest = z.infer<typeof InstallLibrarySkillRequest>;
+
 export const InstalledSkill = z.object({
   capabilityId: z.string().min(1),
   pluginId: z.string().uuid(),
@@ -7613,7 +8165,8 @@ export const InstalledSkill = z.object({
   pluginInstallationId: z.string().uuid(),
   facetInstallationId: z.string().uuid(),
   installationVersion: z.number().int().positive(),
-  source: SkillImportSource,
+  source: SkillInstallationSource,
+  version: z.string().min(1).max(96),
   sourceUrl: z.string().url(),
   sourceCommit: z.string().regex(/^[0-9a-f]{40,64}$/),
   contentSha256: z.string().regex(/^[0-9a-f]{64}$/),
@@ -7629,6 +8182,38 @@ export const CapabilityComponentOwner = z.object({
 });
 export type CapabilityComponentOwner = z.infer<typeof CapabilityComponentOwner>;
 
+export const InstalledSkillSummary = z
+  .object({
+    capabilityId: z.string().min(1),
+    pluginKey: z.string().min(1).max(200),
+    installationVersion: z.number().int().positive(),
+    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),
+    provenance: z.string().min(1).max(4000),
+    source: SkillInstallationSource,
+    version: z.string().min(1).max(96),
+    sourceUrl: z.string().url().max(2048),
+    repositoryUrl: z.string().url().max(2048),
+    sourceCommit: z.string().regex(/^[0-9a-f]{40,64}$/),
+    sourcePath: z.string().min(1).max(1024),
+    contentSha256: z.string().regex(/^[0-9a-f]{64}$/),
+    fileCount: z.number().int().positive().max(128),
+    totalBytes: z.number().int().positive().max(1048576),
+    license: z.string().min(1).max(200).nullable(),
+    installedAt: z.string().datetime({ offset: true }),
+    updatedAt: z.string().datetime({ offset: true }),
+    owners: z.array(CapabilityComponentOwner).min(1),
+  })
+  .strict();
+export type InstalledSkillSummary = z.infer<typeof InstalledSkillSummary>;
+
+export const ListInstalledSkillsResponse = z
+  .object({ skills: z.array(InstalledSkillSummary).max(1000) })
+  .strict();
+export type ListInstalledSkillsResponse = z.infer<typeof ListInstalledSkillsResponse>;
+
 export const SkillUninstallPreview = z.object({
   capabilityId: z.string().min(1),
   installed: z.boolean(),
@@ -7654,26 +8239,29 @@ 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
+export const IntegrationDefinitionProvenance = z.enum(["curated", "workspace"]);
+export type IntegrationDefinitionProvenance = z.infer<typeof IntegrationDefinitionProvenance>;
+
+export const IntegrationFacetKey = z
   .string()
   .min(1)
   .max(200)
   .regex(/^[a-z0-9](?:[a-z0-9._/-]*[a-z0-9])?$/);
-export type IntegrationFeatureKey = z.infer<typeof IntegrationFeatureKey>;
+export type IntegrationFacetKey = z.infer<typeof IntegrationFacetKey>;
 
-export const IntegrationFeatureKind = z.enum([
+export const IntegrationFacetKind = z.enum([
   "tools",
   "knowledge_source",
   "inbound_trigger",
   "delivery_destination",
   "identity_link",
 ]);
-export type IntegrationFeatureKind = z.infer<typeof IntegrationFeatureKind>;
+export type IntegrationFacetKind = z.infer<typeof IntegrationFacetKind>;
 
-export const IntegrationFeatureStatus = z.enum(["active", "paused", "needs_attention", "disabled"]);
-export type IntegrationFeatureStatus = z.infer<typeof IntegrationFeatureStatus>;
+export const IntegrationFacetStatus = z.enum(["active", "paused", "needs_attention", "disabled"]);
+export type IntegrationFacetStatus = z.infer<typeof IntegrationFacetStatus>;
 
-const IntegrationFeatureJsonObject = z.record(z.string(), z.unknown()).superRefine((value, ctx) => {
+const IntegrationFacetJsonObject = z.record(z.string(), z.unknown()).superRefine((value, ctx) => {
   let serialized: string;
   try {
     serialized = JSON.stringify(value);
@@ -7682,40 +8270,50 @@ const IntegrationFeatureJsonObject = z.record(z.string(), z.unknown()).superRefi
     return;
   }
   if (new TextEncoder().encode(serialized).byteLength > 131_072) {
-    ctx.addIssue({ code: "custom", message: "must not exceed 131072 UTF-8 bytes" });
+    ctx.addIssue({
+      code: "custom",
+      message: "must not exceed 131072 UTF-8 bytes",
+    });
   }
 });
 
-export const IntegrationFeatureDefinitionSummary = z
+export const IntegrationFacetDefinitionSummary = z
   .object({
-    featureKey: IntegrationFeatureKey,
-    kind: IntegrationFeatureKind.exclude(["tools"]),
-    configSchema: IntegrationFeatureJsonObject,
-    capabilities: IntegrationFeatureJsonObject,
+    facetKey: IntegrationFacetKey,
+    kind: IntegrationFacetKind.exclude(["tools"]),
+    configSchema: IntegrationFacetJsonObject,
+    capabilities: IntegrationFacetJsonObject,
   })
   .strict();
-export type IntegrationFeatureDefinitionSummary = z.infer<
-  typeof IntegrationFeatureDefinitionSummary
->;
+export type IntegrationFacetDefinitionSummary = z.infer<typeof IntegrationFacetDefinitionSummary>;
 
-export const ApiIntegrationPresetSummary = z
+export const IntegrationDefinitionSummary = 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),
+    provider: z
+      .object({
+        id: z.enum(["google", "microsoft"]),
+        domain: z.string().min(1).max(253),
+      })
+      .strict(),
+    authentication: z
+      .object({
+        kind: z.literal("oauth2"),
+        scopes: z.array(z.string().min(1).max(1024)).max(256),
+      })
+      .strict(),
+    facets: z.array(IntegrationFacetDefinitionSummary).max(128),
   })
   .strict();
-export type ApiIntegrationPresetSummary = z.infer<typeof ApiIntegrationPresetSummary>;
+export type IntegrationDefinitionSummary = z.infer<typeof IntegrationDefinitionSummary>;
 
-export const ListApiIntegrationPresetsResponse = z
-  .object({ presets: z.array(ApiIntegrationPresetSummary).max(128) })
+export const ListIntegrationDefinitionsResponse = z
+  .object({ definitions: z.array(IntegrationDefinitionSummary).max(128) })
   .strict();
-export type ListApiIntegrationPresetsResponse = z.infer<typeof ListApiIntegrationPresetsResponse>;
+export type ListIntegrationDefinitionsResponse = z.infer<typeof ListIntegrationDefinitionsResponse>;
 
 export const IntegrationInstanceKey = z
   .string()
@@ -7724,16 +8322,16 @@ export const IntegrationInstanceKey = z
   .regex(/^[a-z0-9](?:[a-z0-9._/-]*[a-z0-9])?$/);
 export type IntegrationInstanceKey = z.infer<typeof IntegrationInstanceKey>;
 
-export const IntegrationFeatureBindingSummary = z
+export const IntegrationFacetBindingSummary = z
   .object({
     id: z.string().uuid(),
-    featureKey: IntegrationFeatureKey,
-    kind: IntegrationFeatureKind.exclude(["tools"]),
+    facetKey: IntegrationFacetKey,
+    kind: IntegrationFacetKind.exclude(["tools"]),
     bindingKey: IntegrationInstanceKey,
     displayName: z.string().min(1).max(200),
     connectionId: z.string().uuid().nullable(),
-    status: IntegrationFeatureStatus,
-    config: IntegrationFeatureJsonObject,
+    status: IntegrationFacetStatus,
+    config: IntegrationFacetJsonObject,
     version: z.number().int().positive(),
     hasCursor: z.boolean(),
     lastSuccessAt: z.string().datetime({ offset: true }).nullable(),
@@ -7742,73 +8340,76 @@ export const IntegrationFeatureBindingSummary = z
     updatedAt: z.string().datetime({ offset: true }),
   })
   .strict();
-export type IntegrationFeatureBindingSummary = z.infer<typeof IntegrationFeatureBindingSummary>;
+export type IntegrationFacetBindingSummary = z.infer<typeof IntegrationFacetBindingSummary>;
 
-export const IntegrationInstanceFeaturesResponse = z
+export const IntegrationInstanceFacetsResponse = 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
+    facets: z
       .array(
         z
           .object({
-            definition: IntegrationFeatureDefinitionSummary,
-            binding: IntegrationFeatureBindingSummary.nullable(),
+            definition: IntegrationFacetDefinitionSummary,
+            binding: IntegrationFacetBindingSummary.nullable(),
           })
           .strict(),
       )
       .max(128),
   })
   .strict();
-export type IntegrationInstanceFeaturesResponse = z.infer<
-  typeof IntegrationInstanceFeaturesResponse
->;
+export type IntegrationInstanceFacetsResponse = z.infer<typeof IntegrationInstanceFacetsResponse>;
 
-export const UpsertIntegrationFeatureRequest = z
+export const UpsertIntegrationFacetRequest = z
   .object({
     displayName: z.string().min(1).max(200),
-    config: IntegrationFeatureJsonObject.default({}),
+    config: IntegrationFacetJsonObject.default({}),
     expectedVersion: z.number().int().positive().optional(),
     idempotencyKey: z.string().uuid(),
   })
   .strict();
-export type UpsertIntegrationFeatureRequest = z.infer<typeof UpsertIntegrationFeatureRequest>;
+export type UpsertIntegrationFacetRequest = z.infer<typeof UpsertIntegrationFacetRequest>;
 
-export const MutateIntegrationFeatureRequest = z
+export const MutateIntegrationFacetRequest = z
   .object({
     expectedVersion: z.number().int().positive(),
     idempotencyKey: z.string().uuid(),
   })
   .strict();
-export type MutateIntegrationFeatureRequest = z.infer<typeof MutateIntegrationFeatureRequest>;
+export type MutateIntegrationFacetRequest = z.infer<typeof MutateIntegrationFacetRequest>;
 
-export const IntegrationFeatureMutationResult = z
+export const IntegrationFacetMutationResult = z
   .object({
     capabilityId: z.string().min(1).max(512),
     instanceKey: IntegrationInstanceKey,
-    featureKey: IntegrationFeatureKey,
+    facetKey: IntegrationFacetKey,
     status: z.enum(["configured", "paused", "active"]),
-    binding: IntegrationFeatureBindingSummary,
+    binding: IntegrationFacetBindingSummary,
   })
   .strict();
-export type IntegrationFeatureMutationResult = z.infer<typeof IntegrationFeatureMutationResult>;
+export type IntegrationFacetMutationResult = z.infer<typeof IntegrationFacetMutationResult>;
 
-export const IntegrationFeatureRemovalResult = z
+export const IntegrationFacetRemovalResult = z
   .object({
     capabilityId: z.string().min(1).max(512),
     instanceKey: IntegrationInstanceKey,
-    featureKey: IntegrationFeatureKey,
+    facetKey: IntegrationFacetKey,
     status: z.enum(["not_configured", "removed", "retained_by_other_owners"]),
-    binding: IntegrationFeatureBindingSummary.nullable(),
+    binding: IntegrationFacetBindingSummary.nullable(),
     remainingOwners: z.array(CapabilityComponentOwner),
   })
   .strict();
-export type IntegrationFeatureRemovalResult = z.infer<typeof IntegrationFeatureRemovalResult>;
+export type IntegrationFacetRemovalResult = z.infer<typeof IntegrationFacetRemovalResult>;
 
-export const ApiIntegrationSource = z.discriminatedUnion("kind", [
-  z.object({ kind: z.literal("preset"), presetId: z.string().min(1).max(128) }).strict(),
+export const IntegrationSource = z.discriminatedUnion("kind", [
+  z
+    .object({
+      kind: z.literal("definition"),
+      definitionId: z.string().min(1).max(128),
+    })
+    .strict(),
   z
     .object({
       kind: z.literal("openapi"),
@@ -7831,11 +8432,11 @@ export const ApiIntegrationSource = z.discriminatedUnion("kind", [
     })
     .strict(),
 ]);
-export type ApiIntegrationSource = z.infer<typeof ApiIntegrationSource>;
+export type IntegrationSource = z.infer<typeof IntegrationSource>;
 
 export const PreviewApiIntegrationRequest = z
   .object({
-    source: ApiIntegrationSource,
+    source: IntegrationSource,
     connectionId: z.string().uuid().optional(),
     ownership: ConnectionOwnership.optional(),
   })
@@ -7844,7 +8445,7 @@ export type PreviewApiIntegrationRequest = z.infer<typeof PreviewApiIntegrationR
 
 export const ApiIntegrationOAuthStartRequest = z
   .object({
-    presetId: z.string().min(1).max(128),
+    definitionId: z.string().min(1).max(128),
     ownership: ConnectionOwnership.optional(),
     connectionId: z.string().uuid().optional(),
     returnPath: z.string().min(1).max(2048).optional(),
@@ -7861,7 +8462,7 @@ export const ApiIntegrationOAuthConnectionMetadata = z
     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),
+    authorizedDefinitionIds: z.array(z.string().min(1).max(128)).min(1).max(32),
     verifiedAt: z.string().datetime({ offset: true }),
   })
   .passthrough();
@@ -7911,10 +8512,10 @@ export type ApiIntegrationToolPreview = z.infer<typeof ApiIntegrationToolPreview
 
 export const ApiIntegrationPreview = z
   .object({
-    source: ApiIntegrationSource,
-    presetId: z.string().min(1).max(128).nullable(),
+    source: IntegrationSource,
+    definitionId: z.string().min(1).max(200),
+    definitionProvenance: IntegrationDefinitionProvenance,
     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,
@@ -7937,7 +8538,7 @@ export type ApiIntegrationPreview = z.infer<typeof ApiIntegrationPreview>;
 
 export const InstallApiIntegrationRequest = z
   .object({
-    source: ApiIntegrationSource,
+    source: IntegrationSource,
     expectedRevisionId: z.string().min(1).max(96),
     expectedContentSha256: z.string().regex(/^[0-9a-f]{64}$/),
     connectionId: z.string().uuid().optional(),
@@ -7985,7 +8586,8 @@ export const ApiIntegrationInstallationSummary = z
     name: z.string().min(1),
     description: z.string().nullable(),
     protocol: ApiIntegrationProtocol,
-    presetId: z.string().min(1).max(128).nullable(),
+    definitionId: z.string().min(1).max(200),
+    definitionProvenance: IntegrationDefinitionProvenance,
     providerDomain: z.string().min(1),
     baseUrl: z.string().url(),
     sourceUrl: z.string().url().nullable(),
@@ -8065,13 +8667,17 @@ export const PluginManifest = z
       .array(
         z.discriminatedUnion("kind", [
           z
-            .object({ key: PluginComponentKey, kind: z.literal("skill"), url: z.string().url() })
+            .object({
+              key: PluginComponentKey,
+              kind: z.literal("skill"),
+              url: z.string().url(),
+            })
             .strict(),
           z
             .object({
               key: PluginComponentKey,
               kind: z.literal("integration"),
-              source: ApiIntegrationSource,
+              source: IntegrationSource,
             })
             .strict(),
           z
@@ -8166,7 +8772,12 @@ export const InstallPluginRequest = z
     expectedManifestDigest: z.string().regex(/^[0-9a-f]{64}$/),
     expectedComponents: z
       .array(
-        z.object({ key: PluginComponentKey, digest: z.string().regex(/^[0-9a-f]{64}$/) }).strict(),
+        z
+          .object({
+            key: PluginComponentKey,
+            digest: z.string().regex(/^[0-9a-f]{64}$/),
+          })
+          .strict(),
       )
       .min(1)
       .max(64),
@@ -8276,6 +8887,8 @@ export const Session = z.object({
   // the workspace runtime registry.
   effectiveToolPolicy: SessionEffectiveToolPolicy.optional(),
   metadata: z.record(z.string(), z.unknown()),
+  /** Additive public tenancy projection; omitted by legacy/internal readers. */
+  tenancy: SessionTenancyPublicProjection.optional(),
   /** Frozen creator fact used only for creation attribution/idempotent repair. */
   createdBy: TurnInitiator,
   createdByContext: TurnInitiatorContext,
@@ -8307,6 +8920,9 @@ export const Session = z.object({
   // 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),
+  // Workspace channel this session is filed under (rail organization only;
+  // a session tree is grouped by its ROOT session's channel). Null = unfiled.
+  channelId: 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(),
@@ -8486,6 +9102,7 @@ export type SessionLineageResponse = z.infer<typeof SessionLineageResponse>;
 
 export const SessionEventType = z.enum([
   "session.created",
+  "session.visibility.changed",
   // Defensive read/transport projection for a malformed or historically
   // oversized retained event envelope. The original row stays durable; this
   // explicit synthetic type prevents unbounded free-form envelope fields from
@@ -8536,6 +9153,9 @@ export const SessionEventType = z.enum([
   "artifact.created",
   "goal.set",
   "goal.updated",
+  "goal.progress",
+  "goal.rewrite.proposed",
+  "goal.rewrite.rejected",
   "goal.completed",
   "goal.paused",
   "goal.resumed",
@@ -8739,6 +9359,9 @@ export const SESSION_EVENT_SEMANTIC_CLASS_TYPES = {
     "user.humanInputResponse",
     "goal.set",
     "goal.updated",
+    "goal.progress",
+    "goal.rewrite.proposed",
+    "goal.rewrite.rejected",
     "goal.completed",
     "goal.paused",
     "goal.resumed",
@@ -10645,130 +11268,138 @@ export const SessionControlResponse = z.object({
 });
 export type SessionControlResponse = z.infer<typeof SessionControlResponse>;
 
-export const CreateSessionRequest = withVariableSetIdAlias({
-  /**
-   * Optional UUID preallocated by an embedding host. This lets the host durably
-   * link its own projection before OpenGeni admits the initial turn. Replays
-   * must pair it with the same idempotency key; OpenGeni never derives host
-   * identity or authorization from the UUID.
-   */
-  requestedSessionId: z.string().uuid().optional(),
-  initialMessage: z.string().min(1).optional(),
-  // Creates the durable session shell without fabricating a user message or
-  // starting an underlying agent turn. Realtime can then become the first
-  // interaction and use the ordinary Send/Steer path when it delegates.
-  startMode: z.literal("realtime").optional(),
-  // System-level host context for the initial turn only. Unlike `instructions`,
-  // this does not persist into later turns and is never emitted as a user event.
-  turnInstructions: z.string().trim().min(1).max(32768).optional(),
-  // Per-session agent persona/system instructions (org-visible metadata, NOT a
-  // secret). Rides the SAME system-level instructions channel the per-workspace
-  // agentInstructions rides, composed AFTER the workspace persona so it refines
-  // it for this one session — how a host delivers per-agent-type prompts without
-  // 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
-  // variable set variable values). Absent ⇒ byte-identical to today.
-  instructions: z.string().trim().min(1).max(32768).optional(),
-  // Immutable prompt-policy role binding for matching one activated role
-  // policy. This never derives from or grants a human workspace membership
-  // role. Existing callers may continue to use normalized metadata.role as a
-  // compatibility fallback by omitting this field.
-  policyRole: WorkspaceInstructionPolicyRoleKeyInput.optional(),
-  // For an agent-created child, omission inherits the trusted immediate
-  // parent's repository/file context. An explicit array, including [], is
-  // authoritative. Top-level omission remains []. Presence is resolved from
-  // the raw request because this Zod default erases absent-vs-empty.
-  resources: z.array(ResourceRef).default([]),
-  // Inline skills are fixed onto the session. Child omission inherits the
-  // trusted parent's selection; an explicit array, including [], wins.
-  skills: SessionSkills.default([]),
-  // The same child omission rule applies to selected MCP tool refs. Top-level
-  // omission still applies workspace-default capability MCP tools; explicit []
-  // suppresses those defaults (the first-party OpenGeni server remains added).
-  tools: z.array(ToolRef).default([]),
-  metadata: z.record(z.string(), z.unknown()).default({}),
-  model: z.string().min(1).optional(),
-  reasoningEffort: ReasoningEffort.optional(),
-  latencyMode: LatencyMode.optional(),
-  sandboxBackend: SandboxBackend.optional(),
-  // The enrolled machine (a sandbox id) to run this session on; seeds the
-  // active-sandbox pointer at creation so the FIRST turn routes to the chosen
-  // machine (race-free: the pointer is committed before the worker turn
-  // workflow can read it). An invalid/unowned/offline target fails the create.
-  targetSandboxId: z.string().uuid().optional(),
-  // The working directory the targeted machine runs the session under — the
-  // path/cwd base for its agent exec, terminal, and file dock. Free-form pass-
-  // through: a launch-workspace_root-relative subdir or an absolute machine path
-  // (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(),
-  // 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 ⇒ inherit the workspace default;
-  // null ⇒ explicitly create a rig-less session; UUID ⇒ bind that exact rig.
-  // An id that does not name a rig in the workspace is a 422.
-  rigId: z.string().uuid().nullable().optional(),
-  goal: GoalSpec.optional(),
-  clientEventId: SessionOperationKey.optional(),
-  // Workspace-scoped CREATE idempotency key: collapses concurrent/retried
-  // create calls carrying the same key to a single session (partial unique
-  // index on (workspace_id, create_idempotency_key)). Distinct from
-  // clientEventId, whose uniqueness is per-session and so cannot dedup the
-  // creation of a brand-new session. Absent means no create-dedup (each call
-  // is an independent create).
-  idempotencyKey: z.string().min(1).max(200).optional(),
-  // The exact actor-private pre-session draft revision represented by this
-  // create. The durable initializer consumes only this revision. A newer draft
-  // written by a sibling tab survives, while every failed pre-initialization
-  // create leaves the submitted draft intact.
-  expectedNewSessionDraftRevision: z.number().int().nonnegative().optional(),
-  // A child may lower its inherited limit freely; an increase requires
-  // workspace:admin and is checked again at the DB transaction boundary.
-  maxNestedAgentDepth: NestedAgentDepthValue.optional(),
-  // Permissions the session's first-party MCP token should carry. A top-level
-  // omission uses the deployment's worker default; a child omission inherits
-  // the creating session's effective grant. An explicit set is capped at
-  // creation: every requested permission must be held by the creating grant.
-  // A goal-bearing session whose explicit/effective set omits goals:manage is
-  // rejected; creation never silently expands a child beyond that set.
-  firstPartyMcpPermissions: z.array(Permission).optional(),
-  // Exact model-visible selection from the broad first-party OpenGeni MCP
-  // catalog. Omission selects the safe non-connector default; [] intentionally
-  // exposes none.
-  // This does not grant authority: every registered tool is permission-gated.
-  firstPartyMcpTools: z.array(FirstPartyMcpToolName).optional(),
-  // Third-party MCP servers attached only to this session. For an agent-created
-  // child, omission snapshots its trusted immediate parent's server definitions,
-  // policies, connection refs, and encrypted credentials. Explicit arrays,
-  // including [], are authoritative; non-empty explicit arrays require attach
-  // permission. Credential headers are write-only: create responses and events
-  // expose only SessionMcpServerMetadata.
-  mcpServers: z.array(SessionMcpServerInput).max(SESSION_MCP_SERVERS_MAX).default([]),
-  // Shared-sandbox placement (addendum 05 §D.1). Three-way union; OMITTED ⇒
-  // today's behavior (a context-dependent default resolved server-side: from
-  // inside a session → "shared" with the creator's box, top-level → "new").
-  //   - "shared":  join the CREATOR's box. Requires a parent session (inferred
-  //                from the worker-signed sessionId claim, never caller-supplied);
-  //                top-level "shared" is a 422.
-  //   - "new":     mint a fresh singleton box (group ≡ the new session's id).
-  //   - {groupId}: join a SPECIFIC sibling group in THIS workspace (manager
-  //                fan-out). Validated workspace-scoped (cross-workspace → 404).
-  // 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 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(),
-}).superRefine((value, context) => {
+export const CreateSessionRequest = withVariableSetIdAlias(
+  {
+    /**
+     * Optional UUID preallocated by an embedding host. This lets the host durably
+     * link its own projection before OpenGeni admits the initial turn. Replays
+     * must pair it with the same idempotency key; OpenGeni never derives host
+     * identity or authorization from the UUID.
+     */
+    requestedSessionId: z.string().uuid().optional(),
+    initialMessage: z.string().min(1).optional(),
+    // Creates the durable session shell without fabricating a user message or
+    // starting an underlying agent turn. Realtime can then become the first
+    // interaction and use the ordinary Send/Steer path when it delegates.
+    startMode: z.literal("realtime").optional(),
+    // Model-visible application context attached to the initial user message.
+    // Standard timeline rendering omits it, while full event/audit reads retain
+    // it. This is ordinary user-role content, not secret or privileged input.
+    modelContext: z.string().trim().min(1).max(32768).optional(),
+    // Per-session agent persona/system instructions (org-visible metadata, NOT a
+    // secret). Rides the SAME system-level instructions channel the per-workspace
+    // agentInstructions rides, composed AFTER the workspace persona so it refines
+    // it for this one session — how a host delivers per-agent-type prompts without
+    // 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
+    // variable set variable values). Absent ⇒ byte-identical to today.
+    instructions: z.string().trim().min(1).max(32768).optional(),
+    // Immutable prompt-policy role binding for matching one activated role
+    // policy. This never derives from or grants a human workspace membership
+    // role. Existing callers may continue to use normalized metadata.role as a
+    // compatibility fallback by omitting this field.
+    policyRole: WorkspaceInstructionPolicyRoleKeyInput.optional(),
+    // For an agent-created child, omission inherits the trusted immediate
+    // parent's repository/file context. An explicit array, including [], is
+    // authoritative. Top-level omission remains []. Presence is resolved from
+    // the raw request because this Zod default erases absent-vs-empty.
+    resources: z.array(ResourceRef).default([]),
+    // Inline skills are fixed onto the session. Child omission inherits the
+    // trusted parent's selection; an explicit array, including [], wins.
+    skills: SessionSkills.default([]),
+    // The same child omission rule applies to selected MCP tool refs. Top-level
+    // omission still applies workspace-default capability MCP tools; explicit []
+    // suppresses those defaults (the first-party OpenGeni server remains added).
+    tools: z.array(ToolRef).default([]),
+    metadata: z.record(z.string(), z.unknown()).default({}),
+    model: z.string().min(1).optional(),
+    reasoningEffort: ReasoningEffort.optional(),
+    latencyMode: LatencyMode.optional(),
+    sandboxBackend: SandboxBackend.optional(),
+    // The enrolled machine (a sandbox id) to run this session on; seeds the
+    // active-sandbox pointer at creation so the FIRST turn routes to the chosen
+    // machine (race-free: the pointer is committed before the worker turn
+    // workflow can read it). An invalid/unowned/offline target fails the create.
+    targetSandboxId: z.string().uuid().optional(),
+    // The working directory the targeted machine runs the session under — the
+    // path/cwd base for its agent exec, terminal, and file dock. Free-form pass-
+    // through: a launch-workspace_root-relative subdir or an absolute machine path
+    // (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(),
+    // 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 ⇒ inherit the workspace default;
+    // null ⇒ explicitly create a rig-less session; UUID ⇒ bind that exact rig.
+    // An id that does not name a rig in the workspace is a 422.
+    rigId: z.string().uuid().nullable().optional(),
+    // The workspace channel to file this session under (rail organization only).
+    // Omitted/null ⇒ unfiled (inbox). An id that does not name a channel in the
+    // workspace is a 422.
+    channelId: z.string().uuid().nullable().optional(),
+    goal: GoalSpec.optional(),
+    clientEventId: SessionOperationKey.optional(),
+    // Workspace-scoped CREATE idempotency key: collapses concurrent/retried
+    // create calls carrying the same key to a single session (partial unique
+    // index on (workspace_id, create_idempotency_key)). Distinct from
+    // clientEventId, whose uniqueness is per-session and so cannot dedup the
+    // creation of a brand-new session. Absent means no create-dedup (each call
+    // is an independent create).
+    idempotencyKey: z.string().min(1).max(200).optional(),
+    // The exact actor-private pre-session draft revision represented by this
+    // create. The durable initializer consumes only this revision. A newer draft
+    // written by a sibling tab survives, while every failed pre-initialization
+    // create leaves the submitted draft intact.
+    expectedNewSessionDraftRevision: z.number().int().nonnegative().optional(),
+    // A child may lower its inherited limit freely; an increase requires
+    // workspace:admin and is checked again at the DB transaction boundary.
+    maxNestedAgentDepth: NestedAgentDepthValue.optional(),
+    // Permissions the session's first-party MCP token should carry. A top-level
+    // omission uses the deployment's worker default; a child omission inherits
+    // the creating session's effective grant. An explicit set is capped at
+    // creation: every requested permission must be held by the creating grant.
+    // A goal-bearing session whose explicit/effective set omits goals:manage is
+    // rejected; creation never silently expands a child beyond that set.
+    firstPartyMcpPermissions: z.array(Permission).optional(),
+    // Exact model-visible selection from the broad first-party OpenGeni MCP
+    // catalog. Omission selects the safe non-connector default; [] intentionally
+    // exposes none.
+    // This does not grant authority: every registered tool is permission-gated.
+    firstPartyMcpTools: z.array(FirstPartyMcpToolName).optional(),
+    // Third-party MCP servers attached only to this session. For an agent-created
+    // child, omission snapshots its trusted immediate parent's server definitions,
+    // policies, connection refs, and encrypted credentials. Explicit arrays,
+    // including [], are authoritative; non-empty explicit arrays require attach
+    // permission. Credential headers are write-only: create responses and events
+    // expose only SessionMcpServerMetadata.
+    mcpServers: z.array(SessionMcpServerInput).max(SESSION_MCP_SERVERS_MAX).default([]),
+    // Shared-sandbox placement (addendum 05 §D.1). Three-way union; OMITTED ⇒
+    // today's behavior (a context-dependent default resolved server-side: from
+    // inside a session → "shared" with the creator's box, top-level → "new").
+    //   - "shared":  join the CREATOR's box. Requires a parent session (inferred
+    //                from the worker-signed sessionId claim, never caller-supplied);
+    //                top-level "shared" is a 422.
+    //   - "new":     mint a fresh singleton box (group ≡ the new session's id).
+    //   - {groupId}: join a SPECIFIC sibling group in THIS workspace (manager
+    //                fan-out). Validated workspace-scoped (cross-workspace → 404).
+    // 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 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(),
+  },
+  { rejectKeys: ["turnInstructions"] },
+).superRefine((value, context) => {
   if (value.startMode !== "realtime" && value.initialMessage === undefined) {
     context.addIssue({
       code: z.ZodIssueCode.custom,
@@ -10783,6 +11414,13 @@ export const CreateSessionRequest = withVariableSetIdAlias({
       message: "initialMessage must be omitted when startMode is realtime",
     });
   }
+  if (value.startMode === "realtime" && value.modelContext !== undefined) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["modelContext"],
+      message: "modelContext requires an initialMessage; attach it to a realtime entry instead",
+    });
+  }
 });
 export type CreateSessionRequest = z.infer<typeof CreateSessionRequest>;
 
@@ -10969,9 +11607,9 @@ 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(),
+    // Model-visible application context attached to this exact user message.
+    // It is retained in full event/history data but omitted by standard UI.
+    modelContext: z.string().trim().min(1).max(32768).optional(),
     resources: z.array(ResourceRef).default([]),
     model: z.string().min(1).optional(),
     reasoningEffort: ReasoningEffort.optional(),
@@ -11016,8 +11654,8 @@ export const SteerSessionMessageRequest = z
   .object({
     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(),
+    // Same model-visible message context as a queued user.message.
+    modelContext: z.string().trim().min(1).max(32768).optional(),
     resources: z.array(ResourceRef).default([]),
     model: z.string().min(1).optional(),
     reasoningEffort: ReasoningEffort.optional(),
@@ -11171,7 +11809,7 @@ export const SessionCapabilities = z.object({
     reason: CapabilityUnavailableReason.nullable(),
   }),
   Terminal: z.object({
-    transport: z.enum(["sse-events", "pty-ws"]).nullable(),
+    transport: z.enum(["sse-events", "pty-ws", "relay-pty"]).nullable(),
     ptyCapable: z.boolean(),
     shell: z.string(),
     // The direct-to-provider ttyd PTY-over-websocket URL (pty-ws) resolved on the
@@ -11288,7 +11926,7 @@ export const AttachViewerResponse = /* @__PURE__ */ ViewerHolder.extend({
   terminalUrl: z.string().nullable(),
   terminalToken: z.string().nullable(),
   terminalExpiresAt: z.string().nullable(),
-  terminalTransport: z.literal("pty-ws").nullable(),
+  terminalTransport: z.enum(["pty-ws", "relay-pty"]).nullable(),
 });
 export type AttachViewerResponse = z.infer<typeof AttachViewerResponse>;
 
@@ -11828,7 +12466,7 @@ export const ModelCredentialSourceV1 =
       z
         .object({
           kind: z.literal("connected_subscription"),
-          provider: z.literal("codex"),
+          provider: z.enum(["codex", "xai"]),
         })
         .strict(),
       z
@@ -12039,7 +12677,7 @@ export const ClientModel = /* @__PURE__ */ defineModelContractSchema(() =>
     provider: z.string(), // provider id
     providerLabel: z.string(),
     api: z.enum(["responses", "chat"]),
-    source: z.enum(["opengeni", "codex", "workspace_gateway"]).optional(),
+    source: z.enum(["opengeni", "codex", "supergrok", "workspace_gateway"]).optional(),
     contextWindowTokens: z.number().int().positive().optional(),
     // Additive normalized definition metadata. Optional so older server payloads
     // remain parseable; current servers project the complete V1 set.
@@ -12172,7 +12810,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-08-social-provider-tools-v1" as const;
+export const OPENGENI_API_CONTRACT_REVISION = "2026-08-model-context-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;
@@ -12200,6 +12838,15 @@ export const ClientConfig = /* @__PURE__ */ defineModelContractSchema(() =>
         }),
       )
       .default([]),
+    firstPartyMcpTools: z
+      .object({
+        default: z.array(FirstPartyMcpToolName),
+        allowed: z.array(FirstPartyMcpToolName),
+      })
+      .default({
+        default: [...DEFAULT_FIRST_PARTY_MCP_TOOLS],
+        allowed: [...FIRST_PARTY_MCP_TOOL_NAMES],
+      }),
     fileUploads: z.object({
       enabled: z.boolean(),
       maxSizeBytes: z.number().int().positive(),
@@ -12334,9 +12981,13 @@ export function evaluateWorkspaceModelPolicy(
 }
 
 export * from "./codex-fleet-policy";
+export * from "./xai-provider-account-authority";
 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";
+export * from "./knowledge";
+export * from "./task-notes";
+export * from "./canonical-human-identities";