@opengeni/contracts 0.31.1 → 0.35.0

package/src/index.ts

@@ -5,6 +5,7 @@ import {
   sessionEventJsonBytes,
   type SessionEventBoundarySurface,
 } from "./event-preview";
+import { WorkspaceInstructionPolicyRoleKeyInput } from "./workspace-instruction-policies";
 
 export * from "./slack-bot-scopes";
 
@@ -503,7 +504,7 @@ export const CAPABILITY_DESCRIPTORS: Record<SandboxBackend, CapabilityDescriptor
   },
 };
 
-export const ReasoningEffort = z.enum(["none", "minimal", "low", "medium", "high", "xhigh"]);
+export const ReasoningEffort = z.enum(["none", "minimal", "low", "medium", "high", "xhigh", "max"]);
 
 /** Provider service-tier / latency mode selected for a turn or session default. */
 export const LatencyMode = z.enum(["standard", "priority", "fast"]);
@@ -1183,6 +1184,57 @@ export const VOICE_INPUT_ACCEPTED_MIME_TYPES = [
 export const CodexCompactionMode = z.enum(["remote_v2", "portable"]);
 export type CodexCompactionMode = z.infer<typeof CodexCompactionMode>;
 
+export const SlackReactionEmojiName = z
+  .string()
+  .trim()
+  .min(1)
+  .max(64)
+  .regex(/^[a-z0-9_+-]+$/, "use the exact Slack emoji name without surrounding colons");
+export type SlackReactionEmojiName = z.infer<typeof SlackReactionEmojiName>;
+
+export const WorkspaceSlackReactionChannelPolicy = z.discriminatedUnion("mode", [
+  z.object({ mode: z.literal("bot_member") }).strict(),
+  z
+    .object({
+      mode: z.literal("allowlist"),
+      channelIds: z.array(z.string().trim().min(1).max(64)).max(100),
+    })
+    .strict(),
+]);
+export type WorkspaceSlackReactionChannelPolicy = z.infer<
+  typeof WorkspaceSlackReactionChannelPolicy
+>;
+
+export const WorkspaceSlackReactionSummonSettings = z
+  .object({
+    enabled: z.boolean(),
+    emoji: SlackReactionEmojiName,
+    channelPolicy: WorkspaceSlackReactionChannelPolicy,
+  })
+  .strict();
+export type WorkspaceSlackReactionSummonSettings = z.infer<
+  typeof WorkspaceSlackReactionSummonSettings
+>;
+
+export const SlackReactionChannel = z.object({
+  id: z.string().min(1).max(64),
+  name: z.string().min(1).max(256).nullable(),
+  isPrivate: z.boolean(),
+});
+export type SlackReactionChannel = z.infer<typeof SlackReactionChannel>;
+
+export const SlackReactionChannelListResponse = z.object({
+  channels: z.array(SlackReactionChannel).max(200),
+  nextCursor: z.string().max(1_024).nullable(),
+});
+export type SlackReactionChannelListResponse = z.infer<typeof SlackReactionChannelListResponse>;
+
+export const DEFAULT_WORKSPACE_SLACK_REACTION_SUMMON_SETTINGS = {
+  enabled: false,
+  emoji: "genie",
+  channelPolicy: { mode: "bot_member" },
+} as const satisfies WorkspaceSlackReactionSummonSettings;
+
 // Validates the KNOWN keys of workspaces.settings; passthrough keeps unknown
 // (future) keys rather than stripping them. memoryEnabled defaults off;
 // voiceInput defaults to enabled when the deployment has a provider.
@@ -1202,6 +1254,9 @@ export const WorkspaceSettingsSchema = z
     // Default compaction strategy for NEW Codex sessions created in this
     // workspace. Absent ⇒ remote_v2. Non-Codex sessions always freeze portable.
     codexCompactionDefault: CodexCompactionMode.optional(),
+    // Optional Slack reaction invocation. Absent/invalid fails closed to the
+    // disabled default via resolveWorkspaceSlackReactionSummonSettings.
+    slackReactionSummon: WorkspaceSlackReactionSummonSettings.optional(),
   })
   .passthrough();
 export type WorkspaceSettings = z.infer<typeof WorkspaceSettingsSchema>;
@@ -1235,6 +1290,39 @@ export function resolveWorkspaceVoiceInputEnabled(settings: unknown): boolean |
   return null;
 }
 
+export function resolveWorkspaceSlackReactionSummonSettings(
+  settings: unknown,
+): WorkspaceSlackReactionSummonSettings {
+  const parsed = WorkspaceSettingsSchema.safeParse(settings ?? {});
+  const configured = parsed.success ? parsed.data.slackReactionSummon : undefined;
+  if (!configured) {
+    return {
+      enabled: DEFAULT_WORKSPACE_SLACK_REACTION_SUMMON_SETTINGS.enabled,
+      emoji: DEFAULT_WORKSPACE_SLACK_REACTION_SUMMON_SETTINGS.emoji,
+      channelPolicy: { ...DEFAULT_WORKSPACE_SLACK_REACTION_SUMMON_SETTINGS.channelPolicy },
+    };
+  }
+  return configured.channelPolicy.mode === "allowlist"
+    ? {
+        ...configured,
+        channelPolicy: {
+          mode: "allowlist",
+          channelIds: [...new Set(configured.channelPolicy.channelIds)],
+        },
+      }
+    : { ...configured, channelPolicy: { mode: "bot_member" } };
+}
+
+export function workspaceSlackReactionChannelAllowed(
+  settings: WorkspaceSlackReactionSummonSettings,
+  channelId: string,
+): boolean {
+  return (
+    settings.channelPolicy.mode === "bot_member" ||
+    settings.channelPolicy.channelIds.includes(channelId)
+  );
+}
+
 // PATCH body for workspace settings: a partial top-level patch that merges into
 // the stored bag. Nested voiceInput/transcription updates are full replacements;
 // passthrough carries forward-compatible unknown keys.
@@ -1246,6 +1334,7 @@ export const UpdateWorkspaceSettingsRequest = z
     transcription: WorkspaceTranscriptionPolicy.optional(),
     maxNestedAgentDepth: NestedAgentDepthValue.nullable().optional(),
     codexCompactionDefault: CodexCompactionMode.optional(),
+    slackReactionSummon: WorkspaceSlackReactionSummonSettings.optional(),
   })
   .passthrough();
 export type UpdateWorkspaceSettingsRequest = z.infer<typeof UpdateWorkspaceSettingsRequest>;
@@ -2868,6 +2957,14 @@ export const FileResourceRef = z.object({
 });
 export type FileResourceRef = z.infer<typeof FileResourceRef>;
 
+/**
+ * Private durable metadata carried on user history items. It contains only
+ * stable file references, never file bytes, and is removed before model wire
+ * serialization. Keeping the references beside the message lets a later turn
+ * reconstruct the same typed attachment input after a model switch or retry.
+ */
+export const MODEL_ATTACHMENT_REFS_FIELD = "opengeni_attachment_refs" as const;
+
 export const ResourceRef = z.discriminatedUnion("kind", [RepositoryResourceRef, FileResourceRef]);
 export type ResourceRef = z.infer<typeof ResourceRef>;
 
@@ -2954,10 +3051,12 @@ export function defaultRepositoryMountPath(uri: string): string {
 }
 
 /** Resolve the exact mount used by API normalization, manifests, and clone hooks. */
+export const DEFAULT_FILE_RESOURCE_MOUNT_ROOT = ".opengeni/files" as const;
+
 export function resourceMountPath(resource: ResourceRef): string {
   if (resource.mountPath) return normalizeResourceMountPath(resource.mountPath);
   return resource.kind === "file"
-    ? normalizeResourceMountPath(`files/${resource.fileId}`)
+    ? normalizeResourceMountPath(`${DEFAULT_FILE_RESOURCE_MOUNT_ROOT}/${resource.fileId}`)
     : defaultRepositoryMountPath(resource.uri);
 }
 
@@ -3049,8 +3148,15 @@ export type KnowledgeSourceKind = z.infer<typeof KnowledgeSourceKind>;
 export const DocumentSearchMode = z.enum(["hybrid", "vector", "keyword"]);
 export type DocumentSearchMode = z.infer<typeof DocumentSearchMode>;
 
+// Durable document authority. Collections/bases are organizational metadata,
+// never an authorization boundary.
+export const DocumentAuthorityKind = z.enum(["organization", "workspace", "personal"]);
+export type DocumentAuthorityKind = z.infer<typeof DocumentAuthorityKind>;
+
 // 'workspace' documents are readable by anyone with workspace access;
 // 'private' documents are readable only by the grant subject that created them.
+// Retained as a compatibility projection over authorityKind:
+// personal -> private; organization/workspace -> workspace.
 export const DocumentVisibility = z.enum(["workspace", "private"]);
 export type DocumentVisibility = z.infer<typeof DocumentVisibility>;
 
@@ -3109,6 +3215,9 @@ export const Document = z.object({
   sourceUpdatedAt: z.string().nullable(),
   sourceVersion: z.string().nullable(),
   aclTags: z.array(z.string()),
+  authorityKind: DocumentAuthorityKind,
+  authorityWorkspaceId: z.string().uuid().nullable(),
+  authoritySubjectId: z.string().nullable(),
   visibility: DocumentVisibility,
   createdBy: z.string().nullable(),
   agentAccess: z.boolean(),
@@ -3123,6 +3232,9 @@ export type Document = z.infer<typeof Document>;
 
 export const DocumentSearchResult = z.object({
   chunkId: z.string().uuid(),
+  // The workspace that ingested the document. Organization-authority results
+  // may originate in another workspace in the same account; this identifier
+  // is provenance and does not grant access to that workspace or its resources.
   workspaceId: z.string().uuid(),
   documentId: z.string().uuid(),
   baseId: z.string().uuid(),
@@ -3144,9 +3256,17 @@ export const DocumentSearchResult = z.object({
   sourceUpdatedAt: z.string().nullable(),
   sourceVersion: z.string().nullable(),
   aclTags: z.array(z.string()),
+  authorityKind: DocumentAuthorityKind,
+  authorityWorkspaceId: z.string().uuid().nullable(),
+  authoritySubjectId: z.string().nullable(),
 });
 export type DocumentSearchResult = z.infer<typeof DocumentSearchResult>;
 
+export const DocumentSearchResponse = z.object({
+  results: z.array(DocumentSearchResult),
+});
+export type DocumentSearchResponse = z.infer<typeof DocumentSearchResponse>;
+
 export const CreateDocumentBaseRequest = z.object({
   name: z.string().min(1),
   description: z.string().optional(),
@@ -3165,6 +3285,7 @@ export const AddDocumentRequest = z.object({
   sourceUpdatedAt: z.string().datetime({ offset: true }).optional(),
   sourceVersion: z.string().min(1).optional(),
   aclTags: z.array(z.string().min(1)).optional(),
+  authorityKind: DocumentAuthorityKind.optional(),
   visibility: DocumentVisibility.optional(),
   agentAccess: z.boolean().optional(),
 });
@@ -3181,6 +3302,7 @@ export const CreateKnowledgeDropRequest = z
     fileId: z.string().uuid().optional(),
     filename: z.string().min(1).optional(),
     title: z.string().min(1).optional(),
+    authorityKind: DocumentAuthorityKind.optional(),
     visibility: DocumentVisibility.optional(),
     agentAccess: z.boolean().optional(),
   })
@@ -3604,7 +3726,8 @@ export function reasoningEffortForMetadata(
     value === "low" ||
     value === "medium" ||
     value === "high" ||
-    value === "xhigh"
+    value === "xhigh" ||
+    value === "max"
     ? value
     : fallback;
 }
@@ -3898,6 +4021,267 @@ export const SessionAuthorizationSurface = z.enum([
 ]);
 export type SessionAuthorizationSurface = z.infer<typeof SessionAuthorizationSurface>;
 
+// Native connected-Codex GPT-Live WebRTC negotiation. The browser sends its
+// SDP offer, non-provider session configuration, and proof of the exact active
+// ordinary-session realtime owner. The API consumes that proof before resolving
+// the subscription credential and returns only the provider's SDP answer.
+export const CodexRealtimeWebrtcVersion = z.literal("v3");
+export type CodexRealtimeWebrtcVersion = z.infer<typeof CodexRealtimeWebrtcVersion>;
+
+export const CodexRealtimeVoice = z.enum([
+  "juniper",
+  "maple",
+  "spruce",
+  "ember",
+  "vale",
+  "breeze",
+  "arbor",
+  "sol",
+  "cove",
+]);
+export type CodexRealtimeVoice = z.infer<typeof CodexRealtimeVoice>;
+
+const SessionRealtimeOwnerProof = z.object({
+  browserInstanceId: z.string().min(1).max(256),
+  ownerKey: z.string().min(32).max(1024),
+});
+
+export const CodexRealtimeWebrtcRequest = SessionRealtimeOwnerProof.extend({
+  realtimeId: z.string().uuid(),
+  operationId: z.string().uuid(),
+  expectedVersion: z.number().int().positive(),
+  expectedConnectionEpoch: z.number().int().positive(),
+  rotate: z.boolean(),
+  browserActivation: z.literal("required").optional(),
+  sdp: z
+    .string()
+    .min(1)
+    .max(1024 * 1024),
+  version: CodexRealtimeWebrtcVersion,
+  instructions: z.string().max(32_768).optional(),
+  voice: CodexRealtimeVoice.optional(),
+}).strict();
+export type CodexRealtimeWebrtcRequest = z.infer<typeof CodexRealtimeWebrtcRequest>;
+
+export const CodexRealtimeWebrtcResponse = z
+  .object({
+    sdp: z
+      .string()
+      .min(1)
+      .max(1024 * 1024),
+    version: CodexRealtimeWebrtcVersion,
+    model: z.literal("gpt-live-1-boulder-alpha"),
+    connectionId: z.string().uuid(),
+    connectionEpoch: z.number().int().positive(),
+    startupFenceSequence: z.number().int().nonnegative(),
+    modeVersion: z.number().int().positive(),
+    replay: z.boolean(),
+  })
+  .strict();
+export type CodexRealtimeWebrtcResponse = z.infer<typeof CodexRealtimeWebrtcResponse>;
+
+export const GatewayRealtimeConnectRequest = SessionRealtimeOwnerProof.extend({
+  realtimeId: z.string().uuid(),
+  operationId: z.string().uuid(),
+  expectedVersion: z.number().int().positive(),
+  expectedConnectionEpoch: z.number().int().positive(),
+  rotate: z.boolean(),
+}).strict();
+export type GatewayRealtimeConnectRequest = z.infer<typeof GatewayRealtimeConnectRequest>;
+
+export const GatewayRealtimeInitialItem = z.object({
+  role: z.enum(["user", "developer", "assistant"]),
+  text: z.string().min(1).max(131_072),
+});
+export type GatewayRealtimeInitialItem = z.infer<typeof GatewayRealtimeInitialItem>;
+
+export const GatewayRealtimeConnectResponse = z
+  .object({
+    token: z.string().min(1).max(16_384),
+    url: z.string().url(),
+    upstreamModelId: z.string().min(1).max(256),
+    expiresAt: z.number().int().positive().nullable(),
+    connectionId: z.string().uuid(),
+    connectionEpoch: z.number().int().positive(),
+    startupFenceSequence: z.number().int().nonnegative(),
+    modeVersion: z.number().int().positive(),
+    initialItems: z.array(GatewayRealtimeInitialItem).max(128),
+    instructions: z.string().min(1).max(32_768),
+    replay: z.literal(false),
+  })
+  .strict();
+export type GatewayRealtimeConnectResponse = z.infer<typeof GatewayRealtimeConnectResponse>;
+
+export const ActivateCodexRealtimeConnectionRequest = SessionRealtimeOwnerProof.extend({
+  operationId: z.string().uuid(),
+  connectionEpoch: z.number().int().positive(),
+  expectedVersion: z.number().int().positive(),
+  expectedConnectionEpoch: z.number().int().positive(),
+}).strict();
+export type ActivateCodexRealtimeConnectionRequest = z.infer<
+  typeof ActivateCodexRealtimeConnectionRequest
+>;
+
+export const SessionRealtimeLedgerDirection = z.enum(["provider_in", "provider_out"]);
+export type SessionRealtimeLedgerDirection = z.infer<typeof SessionRealtimeLedgerDirection>;
+
+export const SessionRealtimeLedgerKind = z.enum([
+  "user_transcript",
+  "assistant_transcript",
+  "delegation_call",
+  "delegation_progress",
+  "delegation_result",
+  "interruption",
+  "session_update",
+  "error",
+]);
+export type SessionRealtimeLedgerKind = z.infer<typeof SessionRealtimeLedgerKind>;
+
+export const SessionRealtimeLedgerEntry = z
+  .object({
+    id: z.string().uuid(),
+    realtimeId: z.string().uuid(),
+    operationId: z.string().uuid(),
+    connectionEpoch: z.number().int().positive(),
+    sequence: z.number().int().positive(),
+    direction: SessionRealtimeLedgerDirection,
+    kind: SessionRealtimeLedgerKind,
+    role: z.enum(["user", "assistant"]).nullable(),
+    providerEventId: z.string().nullable(),
+    delegationItemId: z.string().nullable(),
+    sourceUpdateId: z.string().uuid().nullable(),
+    historyItemId: z.string().uuid().nullable(),
+    turnId: z.string().uuid().nullable(),
+    text: z.string().nullable(),
+    payload: z.record(z.string(), z.unknown()),
+    clientAckedAt: z.string().datetime().nullable(),
+    providerAckedAt: z.string().datetime().nullable(),
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+  })
+  .strict();
+export type SessionRealtimeLedgerEntry = z.infer<typeof SessionRealtimeLedgerEntry>;
+
+export const SessionRealtimeInboundEntry = z
+  .object({
+    operationId: z.string().uuid(),
+    kind: z.enum([
+      "user_transcript",
+      "assistant_transcript",
+      "delegation_call",
+      "interruption",
+      "error",
+    ]),
+    role: z.enum(["user", "assistant"]).nullable().optional(),
+    providerEventId: z.string().max(1024).nullable().optional(),
+    delegationItemId: z.string().max(1024).nullable().optional(),
+    text: z.string().max(131_072).nullable().optional(),
+    payload: z.record(z.string(), z.unknown()).optional(),
+  })
+  .strict();
+export type SessionRealtimeInboundEntry = z.infer<typeof SessionRealtimeInboundEntry>;
+
+export const SyncSessionRealtimeLedgerRequest = SessionRealtimeOwnerProof.extend({
+  expectedVersion: z.number().int().positive(),
+  connectionId: z.string().uuid(),
+  connectionEpoch: z.number().int().positive(),
+  entries: z.array(SessionRealtimeInboundEntry).max(64).optional(),
+  clientAckThroughSequence: z.number().int().nonnegative().nullable().optional(),
+  providerAckSequences: z.array(z.number().int().positive()).max(100).optional(),
+  providerStarted: z
+    .object({
+      providerSessionId: z.string().min(1).max(1024),
+      providerEventId: z.string().min(1).max(1024).nullable().optional(),
+    })
+    .strict()
+    .optional(),
+}).strict();
+export type SyncSessionRealtimeLedgerRequest = z.infer<typeof SyncSessionRealtimeLedgerRequest>;
+
+export const SyncSessionRealtimeLedgerResponse = z
+  .object({
+    accepted: z.array(
+      z.object({ entry: SessionRealtimeLedgerEntry, replay: z.boolean() }).strict(),
+    ),
+    outbound: z.array(SessionRealtimeLedgerEntry),
+  })
+  .strict();
+export type SyncSessionRealtimeLedgerResponse = z.infer<typeof SyncSessionRealtimeLedgerResponse>;
+
+export const SessionRealtimeModel = z.enum([
+  "gpt-live-1-boulder-alpha",
+  "opengeni-gateway/openai/gpt-realtime-2.1",
+  "opengeni-gateway/openai/gpt-realtime-mini",
+  "opengeni-gateway/xai/grok-voice-think-fast-2.0",
+  "workspace-gateway/openai/gpt-realtime-2.1",
+  "workspace-gateway/openai/gpt-realtime-mini",
+  "workspace-gateway/xai/grok-voice-think-fast-2.0",
+]);
+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"]),
+  description: z.string().min(1),
+  available: z.boolean(),
+  unavailableReason: z.string().nullable(),
+  recommended: z.boolean(),
+});
+export type WorkspaceRealtimeModelCatalogItem = z.infer<typeof WorkspaceRealtimeModelCatalogItem>;
+
+export const WorkspaceRealtimeModelCatalogResponse = z.object({
+  models: z.array(WorkspaceRealtimeModelCatalogItem),
+});
+export type WorkspaceRealtimeModelCatalogResponse = z.infer<
+  typeof WorkspaceRealtimeModelCatalogResponse
+>;
+
+export const SessionRealtimeState = z.enum(["active", "ended"]);
+export type SessionRealtimeState = z.infer<typeof SessionRealtimeState>;
+
+export const SessionRealtimeEndReason = z.enum(["user_stop", "browser_unload", "lease_expired"]);
+export type SessionRealtimeEndReason = z.infer<typeof SessionRealtimeEndReason>;
+
+export const SessionRealtimeMode = z.object({
+  id: z.string().uuid(),
+  sessionId: z.string().uuid(),
+  operationId: z.string().uuid(),
+  browserInstanceId: z.string().min(1).max(256),
+  model: SessionRealtimeModel,
+  state: SessionRealtimeState,
+  version: z.number().int().positive(),
+  connectionEpoch: z.number().int().positive(),
+  leaseExpiresAt: z.string().datetime(),
+  lastHeartbeatAt: z.string().datetime(),
+  startedAt: z.string().datetime(),
+  endedAt: z.string().datetime().nullable(),
+  endReason: SessionRealtimeEndReason.nullable(),
+});
+export type SessionRealtimeMode = z.infer<typeof SessionRealtimeMode>;
+
+export const BeginSessionRealtimeRequest = SessionRealtimeOwnerProof.extend({
+  operationId: z.string().uuid(),
+  model: SessionRealtimeModel,
+});
+export type BeginSessionRealtimeRequest = z.infer<typeof BeginSessionRealtimeRequest>;
+
+export const RenewSessionRealtimeRequest = SessionRealtimeOwnerProof.extend({
+  expectedVersion: z.number().int().positive(),
+});
+export type RenewSessionRealtimeRequest = z.infer<typeof RenewSessionRealtimeRequest>;
+
+export const EndSessionRealtimeRequest = RenewSessionRealtimeRequest.extend({
+  reason: z.enum(["user_stop", "browser_unload"]),
+});
+export type EndSessionRealtimeRequest = z.infer<typeof EndSessionRealtimeRequest>;
+
+export const SessionRealtimeMutationResponse = z.object({
+  mode: SessionRealtimeMode,
+  replay: z.boolean(),
+});
+export type SessionRealtimeMutationResponse = z.infer<typeof SessionRealtimeMutationResponse>;
+
 export const SessionAuthorizationOperation = z.enum([
   "session.read",
   "session.events.read",
@@ -3924,6 +4308,8 @@ export const SessionAuthorizationOperation = z.enum([
   "session.toolspace.call",
   "session.pin.write",
   "session.codex_account.write",
+  "session.realtime.start",
+  "session.realtime.control",
   "session.context.write",
   "session.approval.write",
   "session.human_input.read",
@@ -4246,7 +4632,7 @@ const WorkspaceControlReason = z
   );
 
 export const SessionControlRequest = z.object({
-  action: z.enum(["pause", "resume"]),
+  action: z.enum(["pause", "resume", "cancel"]),
   reason: WorkspaceControlReason.optional(),
   clientEventId: SessionOperationKey,
   expectedControlEtag: z.string().min(1).optional(),
@@ -4494,7 +4880,7 @@ export const SessionSystemUpdatePayload = z.discriminatedUnion("type", [
     .object({
       type: z.literal("child_terminal_result"),
       childSessionId: z.string().uuid(),
-      status: z.enum(["idle", "failed"]),
+      status: z.enum(["idle", "failed", "cancelled"]),
     })
     .passthrough(),
 ]);
@@ -5786,6 +6172,10 @@ export const Session = z.object({
   // metadata (exposed like title/goal), never a secret and never a timeline event.
   // null when the session carried none.
   instructions: z.string().nullable(),
+  // Immutable prompt-policy role binding. This is separate from human
+  // workspace membership roles and from memory selectors. Null keeps the
+  // compatibility fallback to a normalized metadata.role value.
+  policyRole: WorkspaceInstructionPolicyRoleKeyInput.nullable().default(null),
   resources: z.array(ResourceRef),
   skills: SessionSkills.default([]),
   tools: z.array(ToolRef),
@@ -5959,6 +6349,8 @@ export const SessionEventType = z.enum([
   // crossing NATS, SSE, REST, or browser boundaries.
   "session.event.envelope_omitted",
   "session.status.changed",
+  "session.realtime.started",
+  "session.realtime.ended",
   "session.requiresAction",
   "session.humanInput.requested",
   "session.context.compaction.requested",
@@ -7354,7 +7746,12 @@ function compactFailure(
   const code = compactResultStringField(payload.code);
   const recovery = compactResultStringField(payload.recovery);
   const retryable = typeof payload.retryable === "boolean" ? payload.retryable : null;
-  const value = { error: error.value, code: code.value, retryable, recovery: recovery.value };
+  const value = {
+    error: error.value,
+    code: code.value,
+    retryable,
+    recovery: recovery.value,
+  };
   const originalBytes = [error, code, recovery]
     .map((field) => field.originalBytes ?? 0)
     .reduce((sum, bytes) => sum + bytes, 0);
@@ -8045,6 +8442,8 @@ export const SessionControlResponse = z.object({
   effectiveControl: EffectiveSessionControl,
   interruptionCount: z.number().int().nonnegative(),
   wakeCount: z.number().int().nonnegative(),
+  cancelledSessionCount: z.number().int().nonnegative(),
+  cancelledTurnCount: z.number().int().nonnegative(),
 });
 export type SessionControlResponse = z.infer<typeof SessionControlResponse>;
 
@@ -8056,7 +8455,11 @@ export const CreateSessionRequest = withVariableSetIdAlias({
    * identity or authorization from the UUID.
    */
   requestedSessionId: z.string().uuid().optional(),
-  initialMessage: z.string().min(1),
+  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(),
@@ -8069,6 +8472,11 @@ export const CreateSessionRequest = withVariableSetIdAlias({
   // 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
@@ -8102,10 +8510,10 @@ export const CreateSessionRequest = withVariableSetIdAlias({
   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(),
+  // 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
@@ -8162,6 +8570,21 @@ export const CreateSessionRequest = withVariableSetIdAlias({
   sandbox: z
     .union([z.literal("shared"), z.literal("new"), z.object({ groupId: z.string().uuid() })])
     .optional(),
+}).superRefine((value, context) => {
+  if (value.startMode !== "realtime" && value.initialMessage === undefined) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["initialMessage"],
+      message: "initialMessage is required unless startMode is realtime",
+    });
+  }
+  if (value.startMode === "realtime" && value.initialMessage !== undefined) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["initialMessage"],
+      message: "initialMessage must be omitted when startMode is realtime",
+    });
+  }
 });
 export type CreateSessionRequest = z.infer<typeof CreateSessionRequest>;
 
@@ -8189,10 +8612,10 @@ export const HumanInputQuestion = z
     options: z.array(HumanInputOption).max(20).default([]),
     required: z.boolean().default(true),
     allowOther: z.boolean().default(false),
+    // Selection bounds only — agents invent useless text char mins/maxes.
+    // Answer strings stay platform-capped on HumanInputAnswer (~8192).
     validation: z
       .object({
-        minLength: z.number().int().nonnegative().max(8192).nullable().optional(),
-        maxLength: z.number().int().positive().max(8192).nullable().optional(),
         minSelections: z.number().int().nonnegative().max(20).nullable().optional(),
         maxSelections: z.number().int().positive().max(20).nullable().optional(),
       })
@@ -8231,17 +8654,6 @@ export const HumanInputQuestion = z
       });
     }
     const validation = question.validation;
-    if (
-      validation?.minLength != null &&
-      validation?.maxLength != null &&
-      validation.minLength > validation.maxLength
-    ) {
-      ctx.addIssue({
-        code: "custom",
-        path: ["validation"],
-        message: "minLength exceeds maxLength",
-      });
-    }
     if (
       validation?.minSelections != null &&
       validation?.maxSelections != null &&
@@ -9090,9 +9502,8 @@ function defineModelContractSchema<Schema>(factory: () => Schema): Schema {
   return factory();
 }
 
-export const ModelCapabilitySupportV1 = /* @__PURE__ */ defineModelContractSchema(() =>
-  z.enum(["supported", "unsupported", "unknown"]),
-);
+export const ModelCapabilitySupportV1 =
+  /* @__PURE__ */ defineModelContractSchema(() => z.enum(["supported", "unsupported", "unknown"]));
 export type ModelCapabilitySupportV1 = z.infer<typeof ModelCapabilitySupportV1>;
 
 export const ModelCapabilityStateV1 = /* @__PURE__ */ defineModelContractSchema(() =>
@@ -9118,6 +9529,7 @@ export const ModelCapabilitiesV1 = /* @__PURE__ */ defineModelContractSchema(()
       codeExecution: ModelCapabilityStateV1,
     }),
     inputModalities: z.array(z.enum(["text", "image", "audio"])),
+    inputFileMediaTypes: z.array(z.string()).optional(),
     outputModalities: z.array(z.enum(["text", "image", "audio"])),
     transports: z.object({
       sse: ModelCapabilityStateV1,
@@ -9139,37 +9551,54 @@ export const ModelCapabilitiesV1 = /* @__PURE__ */ defineModelContractSchema(()
 );
 export type ModelCapabilitiesV1 = z.infer<typeof ModelCapabilitiesV1>;
 
-export const ModelCredentialSourceV1 = /* @__PURE__ */ defineModelContractSchema(() =>
-  z.union([
-    z
-      .object({ kind: z.literal("deployment"), mechanism: z.enum(["api_key", "azure_ad_bearer"]) })
-      .strict(),
-    z.object({ kind: z.literal("connected_subscription"), provider: z.literal("codex") }).strict(),
-    z.object({ kind: z.literal("workspace_connection"), mechanism: z.literal("api_key") }).strict(),
-  ]),
-);
+export const ModelCredentialSourceV1 =
+  /* @__PURE__ */ defineModelContractSchema(() =>
+    z.union([
+      z
+        .object({
+          kind: z.literal("deployment"),
+          mechanism: z.enum(["api_key", "azure_ad_bearer"]),
+        })
+        .strict(),
+      z
+        .object({
+          kind: z.literal("connected_subscription"),
+          provider: z.literal("codex"),
+        })
+        .strict(),
+      z
+        .object({
+          kind: z.literal("workspace_connection"),
+          mechanism: z.literal("api_key"),
+        })
+        .strict(),
+    ]),
+  );
 export type ModelCredentialSourceV1 = z.infer<typeof ModelCredentialSourceV1>;
 
-export const ModelBillingAttributionV1 = /* @__PURE__ */ defineModelContractSchema(() =>
-  z
-    .object({
-      upstreamPayer: z.enum(["deployment", "workspace", "connected_subscription"]),
-      metering: z.enum(["opengeni_credits", "external"]),
-    })
-    .strict(),
-);
+export const ModelBillingAttributionV1 =
+  /* @__PURE__ */ defineModelContractSchema(() =>
+    z
+      .object({
+        upstreamPayer: z.enum(["deployment", "workspace", "connected_subscription"]),
+        metering: z.enum(["opengeni_credits", "external"]),
+      })
+      .strict(),
+  );
 export type ModelBillingAttributionV1 = z.infer<typeof ModelBillingAttributionV1>;
 
 export const TURN_EXECUTION_POLICY_METADATA_KEY = "turnExecutionPolicyV1" as const;
 
-export const TurnExecutionModelSourceV1 = /* @__PURE__ */ defineModelContractSchema(() =>
-  z.enum(["explicit", "session", "deployment", "continuation"]),
-);
+export const TurnExecutionModelSourceV1 =
+  /* @__PURE__ */ defineModelContractSchema(() =>
+    z.enum(["explicit", "session", "deployment", "continuation"]),
+  );
 export type TurnExecutionModelSourceV1 = z.infer<typeof TurnExecutionModelSourceV1>;
 
-export const TurnExecutionReasoningSourceV1 = /* @__PURE__ */ defineModelContractSchema(() =>
-  z.enum(["explicit", "session", "deployment", "continuation"]),
-);
+export const TurnExecutionReasoningSourceV1 =
+  /* @__PURE__ */ defineModelContractSchema(() =>
+    z.enum(["explicit", "session", "deployment", "continuation"]),
+  );
 export type TurnExecutionReasoningSourceV1 = z.infer<typeof TurnExecutionReasoningSourceV1>;
 
 export const TurnExecutionLatencyModeSourceV1 = /* @__PURE__ */ defineModelContractSchema(() =>
@@ -9374,59 +9803,60 @@ export const ClientModel = /* @__PURE__ */ defineModelContractSchema(() =>
 );
 export type ClientModel = z.infer<typeof ClientModel>;
 
-export const ModelCredentialReadinessV1 = /* @__PURE__ */ defineModelContractSchema(() =>
-  z
-    .object({
-      status: z.enum(["ready", "not_ready", "error"]),
-      reason: z
-        .enum([
-          "missing_credential",
-          "needs_reauth",
-          "prerequisites_missing",
-          "resolver_error",
-          "observation_stale",
-        ])
-        .nullable(),
-      basis: z.enum(["configuration", "connection", "resolver"]),
-      checkedAt: z.string().datetime().nullable(),
-    })
-    .strict()
-    .superRefine((readiness, context) => {
-      if ((readiness.status === "ready") !== (readiness.reason === null)) {
-        context.addIssue({
-          code: "custom",
-          path: ["reason"],
-          message: "ready credential state requires no reason; non-ready state requires a reason",
-        });
-      }
-      if ((readiness.status === "error") !== (readiness.reason === "resolver_error")) {
-        context.addIssue({
-          code: "custom",
-          path: ["reason"],
-          message:
-            "credential errors require resolver_error and resolver_error requires error status",
-        });
-      }
-      if (
-        readiness.basis === "resolver" &&
-        readiness.status === "ready" &&
-        readiness.checkedAt === null
-      ) {
-        context.addIssue({
-          code: "custom",
-          path: ["checkedAt"],
-          message: "resolver readiness requires an observation timestamp",
-        });
-      }
-      if (readiness.reason === "observation_stale" && readiness.checkedAt === null) {
-        context.addIssue({
-          code: "custom",
-          path: ["checkedAt"],
-          message: "a stale observation requires its observation timestamp",
-        });
-      }
-    }),
-);
+export const ModelCredentialReadinessV1 =
+  /* @__PURE__ */ defineModelContractSchema(() =>
+    z
+      .object({
+        status: z.enum(["ready", "not_ready", "error"]),
+        reason: z
+          .enum([
+            "missing_credential",
+            "needs_reauth",
+            "prerequisites_missing",
+            "resolver_error",
+            "observation_stale",
+          ])
+          .nullable(),
+        basis: z.enum(["configuration", "connection", "resolver"]),
+        checkedAt: z.string().datetime().nullable(),
+      })
+      .strict()
+      .superRefine((readiness, context) => {
+        if ((readiness.status === "ready") !== (readiness.reason === null)) {
+          context.addIssue({
+            code: "custom",
+            path: ["reason"],
+            message: "ready credential state requires no reason; non-ready state requires a reason",
+          });
+        }
+        if ((readiness.status === "error") !== (readiness.reason === "resolver_error")) {
+          context.addIssue({
+            code: "custom",
+            path: ["reason"],
+            message:
+              "credential errors require resolver_error and resolver_error requires error status",
+          });
+        }
+        if (
+          readiness.basis === "resolver" &&
+          readiness.status === "ready" &&
+          readiness.checkedAt === null
+        ) {
+          context.addIssue({
+            code: "custom",
+            path: ["checkedAt"],
+            message: "resolver readiness requires an observation timestamp",
+          });
+        }
+        if (readiness.reason === "observation_stale" && readiness.checkedAt === null) {
+          context.addIssue({
+            code: "custom",
+            path: ["checkedAt"],
+            message: "a stale observation requires its observation timestamp",
+          });
+        }
+      }),
+  );
 export type ModelCredentialReadinessV1 = z.infer<typeof ModelCredentialReadinessV1>;
 
 export const ModelAvailabilityV1 = /* @__PURE__ */ defineModelContractSchema(() =>
@@ -9449,19 +9879,21 @@ export const ModelAvailabilityV1 = /* @__PURE__ */ defineModelContractSchema(()
 );
 export type ModelAvailabilityV1 = z.infer<typeof ModelAvailabilityV1>;
 
-export const WorkspaceModelCatalogModel = /* @__PURE__ */ defineModelContractSchema(() =>
-  ClientModel.extend({
-    credentialReadiness: ModelCredentialReadinessV1,
-    availability: ModelAvailabilityV1,
-  }),
-);
+export const WorkspaceModelCatalogModel =
+  /* @__PURE__ */ defineModelContractSchema(() =>
+    ClientModel.extend({
+      credentialReadiness: ModelCredentialReadinessV1,
+      availability: ModelAvailabilityV1,
+    }),
+  );
 export type WorkspaceModelCatalogModel = z.infer<typeof WorkspaceModelCatalogModel>;
 
-export const WorkspaceModelCatalogResponse = /* @__PURE__ */ defineModelContractSchema(() =>
-  z.object({
-    models: z.array(WorkspaceModelCatalogModel),
-  }),
-);
+export const WorkspaceModelCatalogResponse =
+  /* @__PURE__ */ defineModelContractSchema(() =>
+    z.object({
+      models: z.array(WorkspaceModelCatalogModel),
+    }),
+  );
 export type WorkspaceModelCatalogResponse = z.infer<typeof WorkspaceModelCatalogResponse>;
 
 /**