@opengeni/contracts 0.15.0 → 0.19.0

package/src/index.ts

@@ -22,6 +22,30 @@ export {
   type SessionEventPayloadTruncation,
 } from "./event-preview";
 
+export {
+  RETAINED_OUTPUT_DEFAULT_PAGE_BYTES,
+  RETAINED_OUTPUT_MAX_PAGE_BYTES,
+  RETAINED_OUTPUT_RECEIPT_MAX_BYTES,
+  RetainedArtifactMetadataSchema,
+  RetainedArtifactReferenceSchema,
+  RetainedArtifactUnavailableSchema,
+  RetainedOutputEvidenceSchema,
+  RetainedOutputKind,
+  RetainedOutputUnavailableReason,
+  retainedArtifactReferenceFromFile,
+  retainedOutputUnavailable,
+  resolveRetainedOutputRange,
+  validateRetainedOutputEvidence,
+  type RetainedArtifactFileInput,
+  type RetainedArtifactMetadata,
+  type RetainedArtifactReference,
+  type RetainedArtifactUnavailable,
+  type RetainedOutputAvailableEvidence,
+  type RetainedOutputEvidence,
+  type RetainedOutputRangeResolution,
+  type RetainedOutputResolvedRange,
+} from "./retained-output";
+
 export const SessionStatus = z.enum([
   "queued",
   "running",
@@ -444,6 +468,8 @@ export const ErrorCode = z.enum([
   "conflict",
   "idempotency_conflict",
   "limit_exceeded",
+  "nested_agent_depth_exceeded",
+  "nested_agent_depth_override_forbidden",
   "provider_verification_failed",
   "upstream_unavailable",
   "internal_error",
@@ -460,6 +486,45 @@ export const ErrorEnvelope = z.object({
 });
 export type ErrorEnvelope = z.infer<typeof ErrorEnvelope>;
 
+/** Physical ceiling of the PostgreSQL integer columns that persist depth policy. */
+export const MAX_NESTED_AGENT_DEPTH = 2_147_483_647;
+export const NestedAgentDepthValue = z.number().int().nonnegative().max(MAX_NESTED_AGENT_DEPTH);
+export type NestedAgentDepthValue = z.infer<typeof NestedAgentDepthValue>;
+/** A denied child can be one greater than the persisted PostgreSQL int ceiling. */
+export const NestedAgentDepthAttemptValue = z
+  .number()
+  .int()
+  .nonnegative()
+  .max(MAX_NESTED_AGENT_DEPTH + 1);
+
+export const NestedAgentDepthPolicySource = z.enum([
+  "session",
+  "workspace",
+  "deployment",
+  "default",
+]);
+export type NestedAgentDepthPolicySource = z.infer<typeof NestedAgentDepthPolicySource>;
+
+/** Durable evidence for a session-create denial at the database admission boundary. */
+export const SessionSpawnDenial = z.object({
+  id: z.string().uuid(),
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  parentSessionId: z.string().uuid().nullable(),
+  rootSessionId: z.string().uuid().nullable(),
+  currentDepth: NestedAgentDepthValue,
+  attemptedDepth: NestedAgentDepthAttemptValue,
+  effectiveMaxNestedAgentDepth: NestedAgentDepthValue,
+  requestedMaxNestedAgentDepthOverride: NestedAgentDepthValue.nullable(),
+  policySource: NestedAgentDepthPolicySource,
+  policySessionId: z.string().uuid().nullable(),
+  subjectId: z.string().nullable(),
+  code: z.enum(["nested_agent_depth_exceeded", "nested_agent_depth_override_forbidden"]),
+  idempotencyKey: z.string().nullable(),
+  createdAt: z.string(),
+});
+export type SessionSpawnDenial = z.infer<typeof SessionSpawnDenial>;
+
 export const Permission = z.enum([
   "account:read",
   "account:admin",
@@ -535,6 +600,30 @@ export const Permission = z.enum([
 ]);
 export type Permission = z.infer<typeof Permission>;
 
+/**
+ * Capability-first permissions signed into a session's first-party OpenGeni
+ * MCP token when a top-level creator does not explicitly narrow them.
+ *
+ * Keep this contract shared by admission and runtime signing: a worker-signed
+ * child whose parent was narrowed must inherit the parent's effective subset,
+ * never fall back to a different runtime-local default.
+ */
+export const DEFAULT_FIRST_PARTY_MCP_PERMISSIONS = [
+  "workspace:read",
+  "files:read",
+  "documents:search",
+  "scheduled_tasks:manage",
+  "scheduled_tasks:run",
+  "goals:manage",
+  "sessions:read",
+  "sessions:create",
+  "sessions:control",
+  "variable-sets:use",
+  "variable-sets:manage",
+  "rigs:use",
+  "github:use",
+] as const satisfies readonly Permission[];
+
 export function prefixedMcpToolName(registryId: string, toolName: string): string {
   return `${registryId}__${toolName}`;
 }
@@ -886,6 +975,9 @@ export const WorkspaceSettingsSchema = z
   .object({
     memoryEnabled: z.boolean().optional(),
     transcription: WorkspaceTranscriptionPolicy.optional(),
+    // null clears the workspace override and falls back to the persisted
+    // deployment policy. The database boundary validates the same range.
+    maxNestedAgentDepth: NestedAgentDepthValue.nullable().optional(),
   })
   .passthrough();
 export type WorkspaceSettings = z.infer<typeof WorkspaceSettingsSchema>;
@@ -903,6 +995,7 @@ export const UpdateWorkspaceSettingsRequest = z
   .object({
     memoryEnabled: z.boolean().optional(),
     transcription: WorkspaceTranscriptionPolicy.optional(),
+    maxNestedAgentDepth: NestedAgentDepthValue.nullable().optional(),
   })
   .passthrough();
 export type UpdateWorkspaceSettingsRequest = z.infer<typeof UpdateWorkspaceSettingsRequest>;
@@ -1737,11 +1830,39 @@ export type GitCredentialsRequest = {
   repositoryIds: number[];
 };
 
+/**
+ * One exact repository route exposed by a host-owned HTTPS smart-Git broker.
+ *
+ * `repositoryUri` must echo one URI from the request's `repositoryRefs`.
+ * `brokerUri` is a stable, credential-free HTTPS remote. The rotating bearer
+ * remains separate in `GitCredentials.token`, so it cannot leak through Git
+ * configuration, provider-CLI arguments, manifests, or repository metadata.
+ */
+export type GitHttpBrokerRepositoryRoute = {
+  repositoryUri: string;
+  brokerUri: string;
+};
+
+/**
+ * Optional transport override for credentials that cannot be safely narrowed
+ * into a provider token. Omission retains the provider-token behavior.
+ */
+export type GitCredentialTransport = {
+  kind: "http_broker";
+  repositories: GitHttpBrokerRepositoryRoute[];
+};
+
 export type GitCredentials = {
-  // The minted provider token. Required for purpose="token"; optional for
-  // purpose="identity" so hosts can return only stable git identity before lazy
-  // sandbox provision. The value never enters the manifest.
+  // The minted secret. For the default transport this is a provider token; for
+  // `http_broker` it is the broker bearer. Required for purpose="token";
+  // optional for purpose="identity" so hosts can return only stable git identity
+  // before lazy sandbox provision. The value never enters the manifest.
   token?: string;
+  // A host-owned exact smart-Git transport for providers whose available token
+  // cannot be constrained to the selected repositories. OpenGeni rewrites only
+  // the echoed repository remotes and never exposes this bearer to provider
+  // CLIs. Omitted means the token is a direct provider credential.
+  transport?: GitCredentialTransport;
   // workspace-scope cross-check echo: the workspace the provider scoped this token to. The activity
   // asserts `workspaceId === request.workspaceId` before injecting.
   workspaceId: string;
@@ -1964,6 +2085,8 @@ export type McpCredentialsRequest = {
   /** Immediate technical caller, retained only as non-authoritative audit context. */
   callerSubjectId?: string;
   surface: "model" | "toolspace";
+  /** Canonical MCP destination that will receive the resolved headers. */
+  destinationUrl: string;
   serverId: string;
   toolName?: string;
   connectionRef: McpServerConnectionRef;
@@ -2604,6 +2727,63 @@ export const ToolRef = z.object({
 export type ToolRef = z.infer<typeof ToolRef>;
 
 const registryId = /^[A-Za-z0-9_-]+$/;
+export const SessionMcpServerId = z.string().min(1).regex(registryId);
+export type SessionMcpServerId = z.infer<typeof SessionMcpServerId>;
+
+// How a session's persisted `tools` snapshot was selected. `legacy` is
+// reserved for rows written before this descriptor existed; those rows must
+// keep their materialized historical allow-list rather than being guessed to
+// mean either omitted or explicitly empty.
+export const SessionToolPolicy = z.object({
+  mode: z.enum(["workspace_default", "explicit", "inherited", "legacy"]),
+  inheritedFromSessionId: z.string().uuid().nullable(),
+});
+export type SessionToolPolicy = z.infer<typeof SessionToolPolicy>;
+
+export const SESSION_EFFECTIVE_TOOL_POLICY_ID_LIMIT = 64;
+export const SESSION_EFFECTIVE_TOOL_POLICY_ID_MAX_LENGTH = 200;
+const SessionEffectiveToolPolicyId = z
+  .string()
+  .min(1)
+  .max(SESSION_EFFECTIVE_TOOL_POLICY_ID_MAX_LENGTH)
+  .regex(registryId);
+const SessionEffectiveToolPolicyIds = z
+  .array(SessionEffectiveToolPolicyId)
+  .max(SESSION_EFFECTIVE_TOOL_POLICY_ID_LIMIT);
+
+// Secret-safe, read-time policy truth. This projection contains only bounded
+// MCP registry ids and exact counts: never URLs, names, headers, credentials,
+// connector configuration, or tool schemas. IDs are samples when capped;
+// counts remain exact and idsTruncated makes that explicit to clients.
+export const SessionEffectiveToolPolicy = z
+  .object({
+    mode: z.enum(["workspace_default", "explicit", "inherited", "legacy"]),
+    inheritedFromSessionId: z.string().uuid().nullable(),
+    selectedIds: SessionEffectiveToolPolicyIds,
+    effectiveIds: SessionEffectiveToolPolicyIds,
+    mandatoryIds: SessionEffectiveToolPolicyIds,
+    lazyRouter: z
+      .object({
+        state: z.enum(["required", "disabled"]),
+        deferredIds: SessionEffectiveToolPolicyIds,
+      })
+      .strict(),
+    configuredIds: SessionEffectiveToolPolicyIds,
+    droppedIds: SessionEffectiveToolPolicyIds,
+    counts: z
+      .object({
+        selected: z.number().int().nonnegative(),
+        effective: z.number().int().nonnegative(),
+        mandatory: z.number().int().nonnegative(),
+        deferred: z.number().int().nonnegative(),
+        configured: z.number().int().nonnegative(),
+        dropped: z.number().int().nonnegative(),
+      })
+      .strict(),
+    idsTruncated: z.boolean(),
+  })
+  .strict();
+export type SessionEffectiveToolPolicy = z.infer<typeof SessionEffectiveToolPolicy>;
 const httpsUrl = z
   .string()
   .url()
@@ -2618,19 +2798,54 @@ const httpsUrl = z
     { message: "URL must use https" },
   );
 
+/**
+ * Human-approval policy for one MCP server. `true` gates every tool, `false`
+ * gates none, and a list gates only those unprefixed names.
+ */
+export const SESSION_MCP_APPROVAL_POLICY_MAX_TOOL_NAMES = 2_048;
+export const SESSION_MCP_APPROVAL_POLICY_MAX_BYTES = 256 * 1024;
+export const SESSION_MCP_APPROVAL_TOOL_NAME_MAX_BYTES = 1_024;
+export const SESSION_MCP_SERVERS_MAX = 64;
+
+const sessionMcpApprovalToolName = z
+  .string()
+  .min(1)
+  .superRefine((name, ctx) => {
+    if (new TextEncoder().encode(name).byteLength > SESSION_MCP_APPROVAL_TOOL_NAME_MAX_BYTES) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `MCP approval tool names must be at most ${SESSION_MCP_APPROVAL_TOOL_NAME_MAX_BYTES} UTF-8 bytes`,
+      });
+    }
+  });
+const selectiveSessionMcpApprovalPolicy = z
+  .array(sessionMcpApprovalToolName)
+  .max(SESSION_MCP_APPROVAL_POLICY_MAX_TOOL_NAMES)
+  .superRefine((names, ctx) => {
+    const bytes = names.reduce(
+      (total, name) => total + new TextEncoder().encode(name).byteLength,
+      0,
+    );
+    if (bytes > SESSION_MCP_APPROVAL_POLICY_MAX_BYTES) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `MCP approval policies must be at most ${SESSION_MCP_APPROVAL_POLICY_MAX_BYTES} UTF-8 bytes`,
+      });
+    }
+  })
+  .transform((names) => [...new Set(names)].sort());
+export const SessionMcpApprovalPolicy = z.union([z.boolean(), selectiveSessionMcpApprovalPolicy]);
+export type SessionMcpApprovalPolicy = z.infer<typeof SessionMcpApprovalPolicy>;
+
 export const SessionMcpServerInput = z.object({
-  id: z.string().min(1).regex(registryId),
+  id: SessionMcpServerId,
   name: z.string().min(1).optional(),
   url: httpsUrl,
   allowedTools: z.array(z.string().min(1)).optional(),
   timeoutMs: z.number().int().positive().optional(),
   cacheToolsList: z.boolean().optional(),
-  // Human-approval policy for this server's tools. `true` = every tool of this
-  // server requires approval before it runs (a `session.requiresAction` pause
-  // the caller resolves with `user.approvalDecision`); a string[] = ONLY the
-  // listed UNPREFIXED tool names require approval (e.g. reads auto-run, writes
-  // ask); absent / `false` = auto-run everything (the historical default).
-  requireApproval: z.union([z.boolean(), z.array(z.string().min(1))]).optional(),
+  // The caller resolves an approval pause with `user.approvalDecision`.
+  requireApproval: SessionMcpApprovalPolicy.optional(),
   // Write-only credential headers. Values are encrypted at rest and never
   // returned in session responses or events; response metadata exposes names.
   headers: z.record(z.string(), z.string()).optional(),
@@ -2641,23 +2856,43 @@ export const SessionMcpServerInput = z.object({
 export type SessionMcpServerInput = z.infer<typeof SessionMcpServerInput>;
 
 export const SessionMcpCredentialUpdateInput = z.object({
-  id: z.string().min(1).regex(registryId),
+  id: SessionMcpServerId,
   headers: z.record(z.string(), z.string()),
 });
 export type SessionMcpCredentialUpdateInput = z.infer<typeof SessionMcpCredentialUpdateInput>;
 
 export const SessionMcpServerMetadata = z
   .object({
-    id: z.string().min(1).regex(registryId),
+    id: SessionMcpServerId,
     name: z.string().min(1).nullable(),
     url: httpsUrl,
     headerNames: z.array(z.string()).default([]),
     credentialVersion: z.number().int().positive(),
+    requireApproval: SessionMcpApprovalPolicy.default(false),
     connectionRef: McpServerConnectionRef.nullable().default(null),
   })
   .strict();
 export type SessionMcpServerMetadata = z.infer<typeof SessionMcpServerMetadata>;
 
+export const UpdateSessionMcpApprovalPolicyRequest = z
+  .object({
+    requireApproval: SessionMcpApprovalPolicy,
+  })
+  .strict();
+export type UpdateSessionMcpApprovalPolicyRequest = z.infer<
+  typeof UpdateSessionMcpApprovalPolicyRequest
+>;
+
+export const UpdateSessionMcpApprovalPolicyResponse = z
+  .object({
+    server: SessionMcpServerMetadata,
+    effectiveFrom: z.literal("next_attempt"),
+  })
+  .strict();
+export type UpdateSessionMcpApprovalPolicyResponse = z.infer<
+  typeof UpdateSessionMcpApprovalPolicyResponse
+>;
+
 export class ResourceRefConflictError extends Error {
   constructor(message: string) {
     super(message);
@@ -2821,6 +3056,41 @@ export const SessionGoalPausedReason = z.enum([
 ]);
 export type SessionGoalPausedReason = z.infer<typeof SessionGoalPausedReason>;
 
+export const SessionGoalContinuationState = z.enum([
+  "inactive",
+  "scheduled",
+  "running",
+  "blocked",
+  "invariant_broken",
+]);
+export type SessionGoalContinuationState = z.infer<typeof SessionGoalContinuationState>;
+
+export const SessionGoalContinuationReason = z.enum([
+  "goal_inactive",
+  "wake_pending",
+  "continuation_pending",
+  "human_work_pending",
+  "goal_turn_running",
+  "human_turn_running",
+  "workstream_paused",
+  "approval_required",
+  "provider_backpressure",
+  "session_cancelled",
+  "system_work_pending",
+  "missing_obligation",
+]);
+export type SessionGoalContinuationReason = z.infer<typeof SessionGoalContinuationReason>;
+
+export const SessionGoalContinuation = z.object({
+  state: SessionGoalContinuationState,
+  reason: SessionGoalContinuationReason,
+  wakeRevision: z.number().int().nonnegative(),
+  observedRevision: z.number().int().nonnegative(),
+  nextAttemptAt: z.string().datetime({ offset: true }).nullable(),
+  lastError: z.string().nullable(),
+});
+export type SessionGoalContinuation = z.infer<typeof SessionGoalContinuation>;
+
 export const SessionGoal = z.object({
   id: z.string().uuid(),
   accountId: z.string().uuid(),
@@ -2838,6 +3108,9 @@ export const SessionGoal = z.object({
   noProgressStreak: z.number().int().nonnegative(),
   maxAutoContinuations: z.number().int().positive().nullable(),
   metadata: z.record(z.string(), z.unknown()),
+  // Optional for source compatibility with older clients; the API always
+  // supplies this authoritative continuation projection.
+  continuation: SessionGoalContinuation.optional(),
   createdAt: z.string(),
   updatedAt: z.string(),
 });
@@ -3001,6 +3274,7 @@ export const SessionAuthorizationOperation = z.enum([
   "session.human_input.read",
   "session.human_input.write",
   "session.title.write",
+  "session.mcp.approval_policy.write",
   "session.goal.read",
   "session.goal.write",
   "session.child.create",
@@ -3115,6 +3389,10 @@ export const SessionTurn = z.object({
   prompt: z.string().min(1),
   resources: z.array(ResourceRef),
   tools: z.array(ToolRef),
+  // Omitted/default discovery and explicit `tools: []` are distinct. False
+  // inherits the durable session policy; true replaces it for this turn after
+  // admission proves the selection is a subset.
+  toolsProvided: z.boolean().optional(),
   model: z.string().min(1),
   reasoningEffort: ReasoningEffort,
   sandboxBackend: SandboxBackend,
@@ -3204,6 +3482,9 @@ export const ComposerDraft = z.object({
   text: z.string(),
   resources: z.array(ResourceRef),
   tools: z.array(ToolRef),
+  // False means the draft inherits the session policy. True preserves an
+  // explicit array, including [], across autosave/reload and queue checkout.
+  toolsProvided: z.boolean().default(false),
   model: z.string().min(1),
   reasoningEffort: ReasoningEffort,
   sourceTurnId: z.string().uuid().nullable(),
@@ -3260,11 +3541,51 @@ export const SaveComposerDraftRequest = ComposerDraft.pick({
   text: true,
   resources: true,
   tools: true,
+  toolsProvided: true,
   model: true,
   reasoningEffort: true,
 }).extend({ expectedRevision: z.number().int().nonnegative() });
 export type SaveComposerDraftRequest = z.infer<typeof SaveComposerDraftRequest>;
 
+/**
+ * Create-only options saved with an actor's private pre-session draft. This is
+ * deliberately narrower than CreateSessionRequest: idempotency/event keys and
+ * credential-bearing MCP server inputs are per-attempt data, never draft state.
+ */
+export const NewSessionDraftOptions = z.object({
+  sandboxBackend: SandboxBackend.optional(),
+  targetSandboxId: z.string().uuid().optional(),
+  workingDir: z.string().min(1).optional(),
+  variableSetId: z.string().uuid().optional(),
+  rigId: z.string().uuid().optional(),
+  goal: GoalSpec.optional(),
+  firstPartyMcpPermissions: z.array(Permission).optional(),
+});
+export type NewSessionDraftOptions = z.infer<typeof NewSessionDraftOptions>;
+
+/** Actor-private, server-authoritative composer state before a session exists. */
+export const NewSessionDraft = z.object({
+  revision: z.number().int().nonnegative(),
+  text: z.string(),
+  resources: z.array(ResourceRef),
+  tools: z.array(ToolRef),
+  model: z.string().min(1),
+  reasoningEffort: ReasoningEffort,
+  options: NewSessionDraftOptions,
+  updatedAt: z.string().nullable(),
+});
+export type NewSessionDraft = z.infer<typeof NewSessionDraft>;
+
+export const SaveNewSessionDraftRequest = NewSessionDraft.pick({
+  text: true,
+  resources: true,
+  tools: true,
+  model: true,
+  reasoningEffort: true,
+  options: true,
+}).extend({ expectedRevision: z.number().int().nonnegative() });
+export type SaveNewSessionDraftRequest = z.infer<typeof SaveNewSessionDraftRequest>;
+
 export const WORKSPACE_CONTROL_REASON_MAX_BYTES = 8 * 1024;
 export const WORKSPACE_CONTROL_ACTOR_MAX_BYTES = 1024;
 export const WORKSPACE_CONTROL_EVENT_MAX_BYTES = 16 * 1024;
@@ -3838,6 +4159,9 @@ export const ScheduledTaskAgentConfig = z.object({
   reasoningEffort: ReasoningEffort.optional(),
   sandboxBackend: SandboxBackend.optional(),
   goal: GoalSpec.optional(),
+  // Durable task override. Scheduled dispatch is trusted to preserve this
+  // snapshot even if the workspace/deployment policy narrows later.
+  maxNestedAgentDepth: NestedAgentDepthValue.optional(),
 });
 export type ScheduledTaskAgentConfig = z.infer<typeof ScheduledTaskAgentConfig>;
 
@@ -4355,6 +4679,19 @@ export const CapabilityRuntime = z.object({
   mcpServerId: z.string().min(1).optional(),
   transport: z.string().min(1).optional(),
   notes: z.string().nullable().default(null),
+  // Registry exposure provenance is server-derived and contains no endpoint or
+  // credential material.
+  catalogTrust: z
+    .object({
+      state: z.enum(["trusted", "legacy_active", "unverified"]),
+      reason: z.enum([
+        "trusted_source",
+        "verified_probe",
+        "active_installation_compatibility",
+        "missing_verification",
+      ]),
+    })
+    .optional(),
 });
 export type CapabilityRuntime = z.infer<typeof CapabilityRuntime>;
 
@@ -4406,6 +4743,34 @@ export const CapabilityCatalogItem = z.object({
 });
 export type CapabilityCatalogItem = z.infer<typeof CapabilityCatalogItem>;
 
+/**
+ * Shared trust gate for catalog visibility and runtime selection. Registry rows
+ * remain durable for provenance and audit, but only a reviewed real-MCP probe
+ * with known authentication is exposable. API-key rows additionally need a
+ * machine-actionable header contract; prose credential instructions are not a
+ * runtime contract and must fail closed.
+ */
+export function capabilityCatalogItemIsTrustedForExposure(
+  item: Pick<CapabilityCatalogItem, "source" | "stale" | "authKind" | "metadata">,
+): boolean {
+  if (item.stale) return false;
+  if (item.source !== "registry") return true;
+  const probe = item.metadata.mcpProbe;
+  if (!probe || typeof probe !== "object" || Array.isArray(probe)) return false;
+  if ((probe as Record<string, unknown>).status !== "real") return false;
+  if (item.authKind === null || item.authKind === "unknown") return false;
+  if (item.authKind !== "api_key") return true;
+  const contract = item.metadata.authContract;
+  if (!contract || typeof contract !== "object" || Array.isArray(contract)) return false;
+  const record = contract as Record<string, unknown>;
+  return (
+    typeof record.headerName === "string" &&
+    /^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/.test(record.headerName) &&
+    typeof record.scheme === "string" &&
+    record.scheme.trim().length > 0
+  );
+}
+
 export const CapabilityInstallation = z.object({
   id: z.string().uuid(),
   accountId: z.string().uuid(),
@@ -4485,6 +4850,13 @@ export const Session = z.object({
   instructions: z.string().nullable(),
   resources: z.array(ResourceRef),
   tools: z.array(ToolRef),
+  // Origin of the persisted tool allow-list. Optional for rolling client
+  // compatibility; current servers emit it and legacy rows map to `legacy`.
+  toolPolicy: SessionToolPolicy.optional(),
+  // Secret-safe current resolution, computed at an API/read or execution
+  // boundary from IDs only. Optional because internal DB readers need not load
+  // the workspace runtime registry.
+  effectiveToolPolicy: SessionEffectiveToolPolicy.optional(),
   metadata: z.record(z.string(), z.unknown()),
   /** Frozen creator fact used only for creation attribution/idempotent repair. */
   createdBy: TurnInitiator,
@@ -4525,6 +4897,14 @@ export const Session = z.object({
   // direct API creates and scheduled-task runs. When set, this session's
   // terminal-for-now transitions wake the parent.
   parentSessionId: z.string().uuid().nullable(),
+  // Server-authored nested-agent lineage/policy. Root sessions are depth 0;
+  // snapshots are immutable and govern only future descendant creation.
+  rootSessionId: z.string().uuid(),
+  nestedAgentDepth: NestedAgentDepthValue,
+  maxNestedAgentDepthOverride: NestedAgentDepthValue.nullable(),
+  effectiveMaxNestedAgentDepth: NestedAgentDepthValue,
+  nestedAgentDepthPolicySource: NestedAgentDepthPolicySource,
+  nestedAgentDepthPolicySessionId: z.string().uuid().nullable(),
   // Workspace-scoped CREATE idempotency key the session was created under (the
   // dedup target collapsing double-submit/retry races to one session); null
   // when the create carried no key.
@@ -4656,6 +5036,9 @@ export const SessionEventType = z.enum([
   "agent.reasoning.delta",
   "agent.toolCall.created",
   "agent.toolCall.output",
+  // Attempt-fenced Codex Responses lifecycle metadata (request identity,
+  // deadlines, first-byte/terminal phase, provider request id). Never body/auth.
+  "agent.model.request",
   "agent.model.usage",
   "tool.auth_needed",
   "credential.auth_needed",
@@ -4719,6 +5102,7 @@ export const SessionEventType = z.enum([
   "terminal.pty.output.delta", // PTY stdout/stderr bytes (separate from command.output)
   "terminal.pty.exited", // PTY session ended (exitCode/reason)
   "session.title_set",
+  "session.mcp.approval_policy.updated",
   // Multi-account Codex (P1): the account a session's turn runs on changed
   // (manual switch in P1; failover/rotation in P3 reuse the same event). Drives
   // the in-session "Running on:" indicator's live flip.
@@ -4726,6 +5110,10 @@ export const SessionEventType = z.enum([
   // credential allocator per-turn selection audit. Payload is metadata only: credential row
   // id, bounded strategy/reason, and pool counts — never token material.
   "codex.credential.selected",
+  // Adaptive fleet shadow decision record. Contains only bounded opaque candidate aliases,
+  // normalized pressure/cache/confidence features, deterministic fingerprints,
+  // the actual-vs-shadow comparison, and no credential/account identity.
+  "codex.fleet.decision",
   // credential allocator durable zero-capacity wait lifecycle. Runtime/system events only;
   // no synthetic user message is created when capacity returns.
   "codex.capacity.waiting",
@@ -4813,9 +5201,35 @@ export const SessionEventSemanticClass = z.enum([
 ]);
 export type SessionEventSemanticClass = z.infer<typeof SessionEventSemanticClass>;
 
+/**
+ * The semantic classes accepted by an exclusive latest lookup. `receipt` is
+ * the concise public spelling for the historical `tool_receipt` class; the
+ * latter remains accepted everywhere for backwards compatibility.
+ */
+export const SessionEventLatestClass = z.enum([
+  "control",
+  "terminal",
+  "failure",
+  "checkpoint",
+  "tool_receipt",
+  "provider_account",
+  "receipt",
+]);
+export type SessionEventLatestClass = z.infer<typeof SessionEventLatestClass>;
+
+export function sessionEventLatestClassToSemanticClass(
+  value: SessionEventLatestClass,
+): SessionEventSemanticClass {
+  return value === "receipt" ? "tool_receipt" : value;
+}
+
 export const SessionEventPayloadMode = z.enum(["none", "summary", "full"]);
 export type SessionEventPayloadMode = z.infer<typeof SessionEventPayloadMode>;
 
+/** Select the compact semantic-result projection instead of an event array. */
+export const SessionEventResultMode = z.enum(["events", "compact"]);
+export type SessionEventResultMode = z.infer<typeof SessionEventResultMode>;
+
 export const SessionEventReadMode = z.enum(["monitoring", "forensic"]);
 export type SessionEventReadMode = z.infer<typeof SessionEventReadMode>;
 
@@ -4853,9 +5267,11 @@ export const SESSION_EVENT_SEMANTIC_CLASS_TYPES = {
     "workspace.inference.resumed",
     "session.queue.changed",
     "session.queue.prompt.cancelled",
+    "session.mcp.approval_policy.updated",
   ],
   terminal: [
     "turn.completed",
+    "agent.message.completed",
     "turn.failed",
     "turn.cancelled",
     "turn.superseded",
@@ -5167,7 +5583,7 @@ export type TerminalPtyOutputDeltaPayload = z.infer<typeof TerminalPtyOutputDelt
 export const TerminalPtyExitedPayload = z.object({
   ptyId: z.string().uuid(),
   exitCode: z.number().int().nullable(),
-  reason: z.enum(["exit", "killed", "owner_gone", "timeout"]),
+  reason: z.enum(["exit", "killed", "owner_gone", "timeout", "lost"]),
 });
 export type TerminalPtyExitedPayload = z.infer<typeof TerminalPtyExitedPayload>;
 
@@ -5626,7 +6042,8 @@ export type GitShowResponse = z.infer<typeof GitShowResponse>;
 export const TerminalExecRequest = z.object({
   command: z.string().min(1),
   cwd: z.string().default(""), // workspace-relative
-  // Soft per-call wall-clock bound (the box yields output back when reached).
+  // Hard wall-clock bound. A timeout response is returned only after the exact
+  // provider process is physically absent and any retained admission settles.
   timeoutMs: z.number().int().positive().max(120_000).default(30_000),
   // Stream the deltas onto A1 as the agent firehose (so other viewers see it),
   // in addition to returning the buffered result inline.
@@ -5636,10 +6053,10 @@ export type TerminalExecRequest = z.infer<typeof TerminalExecRequest>;
 export const TerminalExecResponse = z.object({
   stdout: z.string(),
   stderr: z.string(),
-  exitCode: z.number().int().nullable(),
-  // True when the process was still running when the call yielded (a long
-  // command); the remaining output drains onto A1 if emitStream was set.
-  running: z.boolean(),
+  exitCode: z.number().int(),
+  // Retained for wire compatibility; synchronous exec never exposes a live
+  // provider process. Interactive work uses the PTY API.
+  running: z.literal(false),
   wallTimeSeconds: z.number().nonnegative(),
 });
 export type TerminalExecResponse = z.infer<typeof TerminalExecResponse>;
@@ -5709,6 +6126,354 @@ export const SessionEvent = z.object({
 });
 export type SessionEvent = z.infer<typeof SessionEvent>;
 
+export type SessionEventCompactResult = {
+  version: 1;
+  semanticClass: SessionEventSemanticClass;
+  source: {
+    id: string;
+    type: SessionEventType;
+    sequence: number;
+    occurredAt: string;
+    turnId: string | null;
+    turnGeneration: number | null;
+    turnAttemptId: string | null;
+    turnAssociation: SessionEvent["turnAssociation"];
+  };
+  // These identity fields are repeated at the top level intentionally: an
+  // MCP caller can act on the result without unpacking the source envelope.
+  id: string;
+  type: SessionEventType;
+  sequence: number;
+  occurredAt: string;
+  turnId: string | null;
+  turnGeneration: number | null;
+  turnAttemptId: string | null;
+  turnAssociation: SessionEvent["turnAssociation"];
+  coveredSequence: { first: number; last: number };
+  status:
+    | "completed"
+    | "failed"
+    | "cancelled"
+    | "superseded"
+    | "checkpoint"
+    | "receipt"
+    | "unknown";
+  text: string | null;
+  output: unknown;
+  result: unknown;
+  failure: {
+    error: string | null;
+    code: string | null;
+    retryable: boolean | null;
+    recovery: string | null;
+  } | null;
+  checkpoint: unknown;
+  receipt: unknown;
+  truncation: {
+    truncated: boolean;
+    fields: string[];
+    originalBytes: number | null;
+    deliveredBytes: number;
+  };
+};
+
+const SESSION_EVENT_COMPACT_RESULT_TEXT_MAX_BYTES = 12 * 1024;
+// Five independently bounded slots plus identity/metadata must fit below the
+// 64 KiB MCP envelope even when a pathological producer supplies every slot.
+const SESSION_EVENT_COMPACT_RESULT_VALUE_MAX_BYTES = 8 * 1024;
+
+type CompactValue = {
+  value: unknown;
+  truncated: boolean;
+  originalBytes: number | null;
+};
+
+type JsonRecord = Record<string, unknown>;
+
+/**
+ * Build the bounded semantic result used by `latest + result=compact`.
+ *
+ * This is intentionally a pure projection over one already-authoritative
+ * event. It never reads history, invokes a model, follows a URL, or stores an
+ * artifact. The DB/API/MCP layers decide which event is authoritative; this
+ * helper only extracts the small result facts that can cross a client boundary.
+ */
+export function compactSessionEventResult(
+  event: SessionEvent,
+  semanticClass: SessionEventSemanticClass,
+  coveredSequence: { first: number; last: number } = {
+    first: event.sequence,
+    last: event.sequence,
+  },
+): SessionEventCompactResult {
+  const payload = isSessionEventJsonRecord(event.payload) ? event.payload : {};
+  const fields: string[] = [];
+  let originalBytes = 0;
+
+  const textCandidate = typeof payload.text === "string" ? payload.text : null;
+  const outputCandidate = Object.prototype.hasOwnProperty.call(payload, "output")
+    ? payload.output
+    : null;
+  const resultCandidate = Object.prototype.hasOwnProperty.call(payload, "result")
+    ? payload.result
+    : undefined;
+  const textValue = textCandidate ?? (typeof outputCandidate === "string" ? outputCandidate : null);
+  const text = textValue === null ? null : compactResultText(textValue);
+  if (text && text.truncated) {
+    fields.push("text");
+    originalBytes += text.originalBytes ?? 0;
+  }
+
+  const output = compactResultValue(outputCandidate);
+  if (outputCandidate !== null && output.truncated) {
+    fields.push("output");
+    originalBytes += output.originalBytes ?? 0;
+  }
+
+  const result = compactResultValue(
+    resultCandidate === undefined ? (textValue ?? outputCandidate) : resultCandidate,
+  );
+  if (resultCandidate !== undefined && result.truncated) {
+    fields.push("result");
+    originalBytes += result.originalBytes ?? 0;
+  }
+
+  const checkpointField = firstOwnPayloadValue(payload, ["checkpoint", "summary", "snapshot"]);
+  const checkpointCandidate =
+    checkpointField !== undefined
+      ? checkpointField
+      : semanticClass === "checkpoint"
+        ? payload
+        : null;
+  const checkpoint = compactResultValue(checkpointCandidate);
+  if (checkpointCandidate !== null && checkpoint.truncated) {
+    fields.push("checkpoint");
+    originalBytes += checkpoint.originalBytes ?? 0;
+  }
+
+  const receiptCandidate = firstOwnPayloadValue(payload, ["receipt", "receiptData"]);
+  const receipt = compactResultValue(
+    receiptCandidate !== undefined
+      ? receiptCandidate
+      : semanticClass === "tool_receipt"
+        ? payload
+        : null,
+  );
+  if (receipt.truncated) {
+    fields.push("receipt");
+    originalBytes += receipt.originalBytes ?? 0;
+  }
+
+  const failure = compactFailure(payload, event.type);
+  if (failure.truncated) {
+    fields.push("failure");
+    originalBytes += failure.originalBytes ?? 0;
+  }
+
+  if (isSessionEventJsonRecord(payload.truncation) && payload.truncation.truncated === true) {
+    fields.push("payload");
+  }
+
+  const source = {
+    id: event.id,
+    type: event.type,
+    sequence: event.sequence,
+    occurredAt: event.occurredAt,
+    turnId: event.turnId ?? null,
+    turnGeneration: event.turnGeneration ?? null,
+    turnAttemptId: event.turnAttemptId ?? null,
+    turnAssociation: event.turnAssociation ?? null,
+  };
+  const status = compactResultStatus(event.type, semanticClass, payload);
+  const outputValue = outputCandidate === null ? null : output.value;
+  const resultValue = result.value;
+  const checkpointValue = checkpointCandidate === null ? null : checkpoint.value;
+  const receiptValue =
+    receiptCandidate === null && semanticClass !== "tool_receipt" ? null : receipt.value;
+  const compact: SessionEventCompactResult = {
+    version: 1,
+    semanticClass,
+    source,
+    id: source.id,
+    type: source.type,
+    sequence: source.sequence,
+    occurredAt: source.occurredAt,
+    turnId: source.turnId,
+    turnGeneration: source.turnGeneration,
+    turnAttemptId: source.turnAttemptId,
+    turnAssociation: source.turnAssociation,
+    coveredSequence,
+    status,
+    text: text?.value ?? null,
+    output: outputValue,
+    result: resultValue,
+    failure: failure.value,
+    checkpoint: checkpointValue,
+    receipt: receiptValue,
+    truncation: {
+      truncated: fields.length > 0,
+      fields: [...new Set(fields)],
+      originalBytes: fields.length > 0 ? originalBytes || null : null,
+      deliveredBytes: sessionEventJsonBytes({
+        text: text?.value ?? null,
+        output: outputValue,
+        result: resultValue,
+        failure: failure.value,
+        checkpoint: checkpointValue,
+        receipt: receiptValue,
+      }),
+    },
+  };
+  return compact;
+}
+
+function isSessionEventJsonRecord(value: unknown): value is JsonRecord {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function firstOwnPayloadValue(payload: JsonRecord, keys: readonly string[]): unknown | undefined {
+  for (const key of keys) {
+    if (Object.prototype.hasOwnProperty.call(payload, key)) return payload[key];
+  }
+  return undefined;
+}
+
+function compactResultText(value: string): CompactValue & { value: string } {
+  const originalBytes = new TextEncoder().encode(value).byteLength;
+  if (originalBytes <= SESSION_EVENT_COMPACT_RESULT_TEXT_MAX_BYTES) {
+    return { value, truncated: false, originalBytes };
+  }
+  let omittedBytes = originalBytes - SESSION_EVENT_COMPACT_RESULT_TEXT_MAX_BYTES;
+  let projected = value;
+  for (let attempt = 0; attempt < 4; attempt += 1) {
+    const marker = `…[${omittedBytes} UTF-8 bytes omitted from compact result]…`;
+    const budget = Math.max(0, SESSION_EVENT_COMPACT_RESULT_TEXT_MAX_BYTES - utf8Bytes(marker));
+    const head = utf8PrefixForResult(value, Math.floor(budget * 0.7));
+    const tail = utf8SuffixForResult(value, budget - utf8Bytes(head));
+    projected = `${head}${marker}${tail}`;
+    const nextOmitted = Math.max(0, originalBytes - utf8Bytes(head) - utf8Bytes(tail));
+    if (nextOmitted === omittedBytes) break;
+    omittedBytes = nextOmitted;
+  }
+  return { value: projected, truncated: true, originalBytes };
+}
+
+function compactResultValue(value: unknown): CompactValue {
+  if (value === null || value === undefined) {
+    return { value: null, truncated: false, originalBytes: null };
+  }
+  const measurement = measureSessionEventJson(value);
+  const bounded = boundSessionEventPayload(value, {
+    surface: "http_projection",
+    maxBytes: SESSION_EVENT_COMPACT_RESULT_VALUE_MAX_BYTES,
+  });
+  const deliveredBytes = measureSessionEventJson(bounded).bytes;
+  return {
+    value: bounded,
+    truncated:
+      measurement.bytes === null || deliveredBytes === null || measurement.bytes !== deliveredBytes,
+    originalBytes: measurement.bytes,
+  };
+}
+
+function compactFailure(
+  payload: JsonRecord,
+  eventType: SessionEventType,
+): CompactValue & {
+  value: SessionEventCompactResult["failure"];
+} {
+  const isFailure =
+    eventType === "turn.failed" ||
+    eventType === "turn.cancelled" ||
+    eventType === "turn.superseded";
+  const hasFailureField = ["error", "code", "retryable", "recovery"].some((key) =>
+    Object.prototype.hasOwnProperty.call(payload, key),
+  );
+  if (!isFailure && !hasFailureField) {
+    return { value: null, truncated: false, originalBytes: null };
+  }
+  const error = compactResultStringField(payload.error);
+  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 originalBytes = [error, code, recovery]
+    .map((field) => field.originalBytes ?? 0)
+    .reduce((sum, bytes) => sum + bytes, 0);
+  return {
+    value,
+    truncated: error.truncated || code.truncated || recovery.truncated,
+    originalBytes: originalBytes || null,
+  };
+}
+
+function compactResultStringField(value: unknown): CompactValue & { value: string | null } {
+  if (typeof value !== "string") {
+    return { value: null, truncated: false, originalBytes: null };
+  }
+  return compactResultText(value);
+}
+
+function compactResultStatus(
+  eventType: SessionEventType,
+  semanticClass: SessionEventSemanticClass,
+  payload: JsonRecord,
+): SessionEventCompactResult["status"] {
+  if (eventType === "turn.failed") return "failed";
+  if (eventType === "turn.cancelled") return "cancelled";
+  if (eventType === "turn.superseded") return "superseded";
+  if (eventType === "turn.completed" || eventType === "agent.message.completed") {
+    return "completed";
+  }
+  if (semanticClass === "checkpoint") return "checkpoint";
+  if (
+    semanticClass === "tool_receipt" ||
+    eventType === "artifact.created" ||
+    eventType === "recording.available"
+  ) {
+    return "receipt";
+  }
+  if (payload.status === "failed") return "failed";
+  if (payload.status === "completed") return "completed";
+  return "unknown";
+}
+
+function utf8Bytes(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}
+
+function utf8PrefixForResult(value: string, maxBytes: number): string {
+  let bytes = 0;
+  let index = 0;
+  while (index < value.length) {
+    const codePoint = value.codePointAt(index);
+    if (codePoint === undefined) break;
+    const character = String.fromCodePoint(codePoint);
+    const next = utf8Bytes(character);
+    if (bytes + next > maxBytes) break;
+    bytes += next;
+    index += character.length;
+  }
+  return value.slice(0, index);
+}
+
+function utf8SuffixForResult(value: string, maxBytes: number): string {
+  let bytes = 0;
+  let index = value.length;
+  while (index > 0) {
+    const width =
+      index > 1 && value.charCodeAt(index - 1) >= 0xdc00 && value.charCodeAt(index - 1) <= 0xdfff
+        ? 2
+        : 1;
+    const character = value.slice(index - width, index);
+    const next = utf8Bytes(character);
+    if (bytes + next > maxBytes) break;
+    bytes += next;
+    index -= width;
+  }
+  return value.slice(index);
+}
+
 // --- Durable host export ------------------------------------------------------
 
 /** Wire revision for the durable host event/usage export stream. */
@@ -6388,6 +7153,14 @@ export const CreateSessionRequest = withVariableSetIdAlias({
   // 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
@@ -6401,7 +7174,7 @@ export const CreateSessionRequest = withVariableSetIdAlias({
   // 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).default([]),
+  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").
@@ -6770,6 +7543,9 @@ export const SessionCapabilities = z.object({
   liveness: z.enum(["cold", "warming", "warm", "draining"]),
   // Echoed on viewer heartbeats (the split-brain fence).
   leaseEpoch: z.number().int().nonnegative(),
+  workspaceGeneration: z.number().int().nonnegative().nullable().default(null),
+  archiveGeneration: z.number().int().nonnegative().nullable().default(null),
+  archiveComplete: z.boolean().default(false),
   viewerHeartbeatIntervalMs: z.number().int().positive().default(30_000),
   FileSystem: z.object({
     available: z.boolean(),
@@ -6874,6 +7650,9 @@ export const ViewerHolder = z.object({
   liveness: z.enum(["cold", "warming", "warm", "draining"]),
   // The epoch the viewer is fenced on; echoed back on heartbeats.
   leaseEpoch: z.number().int().nonnegative(),
+  workspaceGeneration: z.number().int().nonnegative().nullable(),
+  archiveGeneration: z.number().int().nonnegative().nullable(),
+  archiveComplete: z.boolean(),
   viewerHeartbeatIntervalMs: z.number().int().positive(),
   // The desktop pixel tunnel URL the viewer connects to directly; null until
   // a viewer grant is minted (gated until then).
@@ -7237,6 +8016,9 @@ export const MachineView = z.object({
   state: MachineState,
   active: z.boolean(),
   isSessionGroup: z.boolean(),
+  workspaceGeneration: z.number().int().nonnegative().nullable(),
+  archiveGeneration: z.number().int().nonnegative().nullable(),
+  archiveComplete: z.boolean(),
   os: z.string(),
   arch: z.string(),
   hasDisplay: z.boolean(),
@@ -7296,6 +8078,9 @@ export const SwapActiveSandboxResponse = z.object({
       "unsupported_backend_context",
       "transient_establishment",
       "concurrent_swap",
+      "recovery_in_progress",
+      "recovery_degraded",
+      "recovery_unrecoverable",
     ])
     .optional(),
 });
@@ -7310,6 +8095,239 @@ export const MachineMetricsSeriesResponse = z.object({
 });
 export type MachineMetricsSeriesResponse = z.infer<typeof MachineMetricsSeriesResponse>;
 
+/**
+ * Keep this server-facing schema graph eager when imported while allowing
+ * browser bundlers to discard it when contracts is used only for unrelated
+ * helpers. Keep each call site annotated as pure; the factory argument itself
+ * is side-effect-free until invoked.
+ */
+function defineModelContractSchema<Schema>(factory: () => Schema): Schema {
+  return factory();
+}
+
+export const ModelCapabilitySupportV1 = /* @__PURE__ */ defineModelContractSchema(() =>
+  z.enum(["supported", "unsupported", "unknown"]),
+);
+export type ModelCapabilitySupportV1 = z.infer<typeof ModelCapabilitySupportV1>;
+
+export const ModelCapabilityStateV1 = /* @__PURE__ */ defineModelContractSchema(() =>
+  z.object({
+    upstream: ModelCapabilitySupportV1,
+    runnable: z.boolean(),
+  }),
+);
+export type ModelCapabilityStateV1 = z.infer<typeof ModelCapabilityStateV1>;
+
+export const ModelCapabilitiesV1 = /* @__PURE__ */ defineModelContractSchema(() =>
+  z.object({
+    reasoning: ModelCapabilityStateV1.extend({
+      efforts: z.array(ReasoningEffort),
+      defaultEffort: ReasoningEffort.nullable(),
+      required: z.boolean(),
+    }),
+    functionCalling: ModelCapabilityStateV1,
+    structuredOutput: ModelCapabilityStateV1,
+    hostedTools: z.object({
+      webSearch: ModelCapabilityStateV1,
+      xSearch: ModelCapabilityStateV1,
+      codeExecution: ModelCapabilityStateV1,
+    }),
+    inputModalities: z.array(z.enum(["text", "image", "audio"])),
+    outputModalities: z.array(z.enum(["text", "image", "audio"])),
+    transports: z.object({
+      sse: ModelCapabilityStateV1,
+      responsesWebSocket: ModelCapabilityStateV1,
+      realtimeAudio: ModelCapabilityStateV1,
+    }),
+    latencyModes: z.array(
+      z.object({
+        id: z.enum(["standard", "priority", "fast"]),
+        upstream: ModelCapabilitySupportV1,
+        runnable: z.boolean(),
+        billingMultiplierBps: z.number().int().positive().optional(),
+      }),
+    ),
+  }),
+);
+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 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 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 type TurnExecutionModelSourceV1 = z.infer<typeof TurnExecutionModelSourceV1>;
+
+export const TurnExecutionReasoningSourceV1 = /* @__PURE__ */ defineModelContractSchema(() =>
+  z.enum(["explicit", "session", "deployment", "continuation"]),
+);
+export type TurnExecutionReasoningSourceV1 = z.infer<typeof TurnExecutionReasoningSourceV1>;
+
+/**
+ * Secret-safe execution identity frozen onto one accepted logical turn.
+ *
+ * This is deliberately a strict, normalized reference to the deployment
+ * definition rather than a serialized provider client. It must never contain
+ * a key/token, concrete connected credential id, account label, authorization
+ * header, or credential-bearing URL/query value.
+ */
+export const TurnExecutionPolicyV1 = /* @__PURE__ */ defineModelContractSchema(() =>
+  z
+    .object({
+      schemaVersion: z.literal(1),
+      productModelId: z.string().min(1),
+      requestedModelId: z.string().min(1).nullable(),
+      modelSource: TurnExecutionModelSourceV1,
+      reasoningEffort: ReasoningEffort,
+      reasoningSource: TurnExecutionReasoningSourceV1,
+      providerId: z.string().min(1),
+      upstreamModelId: z.string().min(1),
+      wireApi: z.enum(["responses", "chat"]),
+      credentialSource: ModelCredentialSourceV1,
+      billing: ModelBillingAttributionV1,
+      definitionVersion: z.string().regex(/^sha256:[a-f0-9]{64}$/u),
+    })
+    .strict()
+    .superRefine((policy, context) => {
+      if (policy.modelSource === "explicit" && policy.requestedModelId === null) {
+        context.addIssue({
+          code: "custom",
+          path: ["requestedModelId"],
+          message: "an explicit model source requires a requested model id",
+        });
+      }
+      if (policy.modelSource !== "explicit" && policy.requestedModelId !== null) {
+        context.addIssue({
+          code: "custom",
+          path: ["requestedModelId"],
+          message: "only an explicit model source may retain a requested model id",
+        });
+      }
+    }),
+);
+export type TurnExecutionPolicyV1 = z.infer<typeof TurnExecutionPolicyV1>;
+
+export type TurnExecutionPolicyReadV1 =
+  | { kind: "absent" }
+  | { kind: "valid"; policy: TurnExecutionPolicyV1 };
+
+/**
+ * Read the policy from turn metadata. Only a literally absent key is legacy;
+ * null, undefined, an unknown schema version, extra fields, and every other
+ * malformed present value fail closed. Error text reports paths only and never
+ * reflects the untrusted value into logs or events.
+ */
+export function readTurnExecutionPolicyV1(metadata: unknown): TurnExecutionPolicyReadV1 {
+  if (metadata === null || metadata === undefined) {
+    return { kind: "absent" };
+  }
+  if (typeof metadata !== "object" || Array.isArray(metadata)) {
+    throw new Error("Malformed turn execution policy metadata: turn metadata is not an object");
+  }
+  const record = metadata as Record<string, unknown>;
+  if (!Object.prototype.hasOwnProperty.call(record, TURN_EXECUTION_POLICY_METADATA_KEY)) {
+    return { kind: "absent" };
+  }
+  const parsed = TurnExecutionPolicyV1.safeParse(record[TURN_EXECUTION_POLICY_METADATA_KEY]);
+  if (!parsed.success) {
+    const paths = [
+      ...new Set(
+        parsed.error.issues.map((issue) =>
+          issue.path.length === 0 ? "policy" : `policy.${issue.path.join(".")}`,
+        ),
+      ),
+    ].join(", ");
+    throw new Error(`Malformed turn execution policy metadata at ${paths || "policy"}`);
+  }
+  return { kind: "valid", policy: parsed.data };
+}
+
+/** Merge a trusted policy into metadata without disturbing dispatch/recovery state. */
+export function metadataWithTurnExecutionPolicyV1(
+  metadata: Readonly<Record<string, unknown>> | null | undefined,
+  policy: TurnExecutionPolicyV1,
+): Record<string, unknown> {
+  return {
+    ...(metadata ?? {}),
+    [TURN_EXECUTION_POLICY_METADATA_KEY]: TurnExecutionPolicyV1.parse(policy),
+  };
+}
+
+/**
+ * Minimal, stable evidence projection for command receipts and audit events.
+ * It intentionally excludes aliases, URLs, request metadata, and all concrete
+ * credential-selection identity.
+ */
+export function turnExecutionPolicyAuditMetadata(
+  policy: TurnExecutionPolicyV1,
+  turnId: string,
+): Record<string, unknown> {
+  const parsed = TurnExecutionPolicyV1.parse(policy);
+  return {
+    turnId,
+    requestedModelId: parsed.requestedModelId,
+    effectiveModelId: parsed.productModelId,
+    modelSource: parsed.modelSource,
+    effectiveReasoningEffort: parsed.reasoningEffort,
+    reasoningSource: parsed.reasoningSource,
+    providerId: parsed.providerId,
+    credentialSourceKind: parsed.credentialSource.kind,
+    credentialSourceMechanism:
+      parsed.credentialSource.kind === "connected_subscription"
+        ? parsed.credentialSource.provider
+        : parsed.credentialSource.mechanism,
+    billingOwner: parsed.billing.upstreamPayer,
+    billingMetering: parsed.billing.metering,
+    definitionVersion: parsed.definitionVersion,
+  };
+}
+
+export const ModelPricingV1 = /* @__PURE__ */ defineModelContractSchema(() =>
+  z.object({
+    inputMicrosPerMillionTokens: z.number().int().nonnegative(),
+    cachedInputMicrosPerMillionTokens: z.number().int().nonnegative().optional(),
+    outputMicrosPerMillionTokens: z.number().int().nonnegative(),
+    marginBps: z.number().int().min(0).max(100_000).optional(),
+  }),
+);
+export type ModelPricingV1 = z.infer<typeof ModelPricingV1>;
+
+export const ModelPricingScheduleV1 = /* @__PURE__ */ defineModelContractSchema(() =>
+  z.object({
+    default: ModelPricingV1,
+    inputTokenTiers: z
+      .array(
+        z.object({
+          minimumInputTokens: z.number().int().nonnegative(),
+          pricing: ModelPricingV1,
+        }),
+      )
+      .optional(),
+  }),
+);
+export type ModelPricingScheduleV1 = z.infer<typeof ModelPricingScheduleV1>;
+
 /**
  * A single host-exposed model + the provider that serves it, as surfaced to
  * clients (SDK + React composer) by GET /v1/config/client. The wire `api`
@@ -7317,16 +8335,134 @@ export type MachineMetricsSeriesResponse = z.infer<typeof MachineMetricsSeriesRe
  * provider id/label drive the picker's grouping. This mirrors the runtime's
  * ConfiguredModel (packages/config) projected to the client-safe fields.
  */
-export const ClientModel = z.object({
-  id: z.string(),
-  label: z.string(),
-  provider: z.string(), // provider id
-  providerLabel: z.string(),
-  api: z.enum(["responses", "chat"]),
-  contextWindowTokens: z.number().int().positive().optional(),
-});
+export const ClientModel = /* @__PURE__ */ defineModelContractSchema(() =>
+  z.object({
+    id: z.string(),
+    label: z.string(),
+    provider: z.string(), // provider id
+    providerLabel: z.string(),
+    api: z.enum(["responses", "chat"]),
+    contextWindowTokens: z.number().int().positive().optional(),
+    // Additive normalized definition metadata. Optional so older server payloads
+    // remain parseable; current servers project the complete V1 set.
+    schemaVersion: z.literal(1).optional(),
+    aliases: z.array(z.string()).optional(),
+    deployment: z
+      .object({
+        upstreamModelId: z.string().min(1),
+        wireApi: z.enum(["responses", "chat"]),
+      })
+      .optional(),
+    executionLimits: z
+      .object({
+        contextWindowTokens: z.number().int().positive().nullable(),
+        effectiveContextWindowTokens: z.number().int().positive().nullable(),
+        autoCompactTokenLimit: z.number().int().positive().nullable(),
+        toolOutputTruncationTokens: z.number().int().positive().nullable(),
+      })
+      .optional(),
+    credentialSource: ModelCredentialSourceV1.optional(),
+    billing: ModelBillingAttributionV1.optional(),
+    capabilities: ModelCapabilitiesV1.optional(),
+    pricing: ModelPricingScheduleV1.optional(),
+    definitionVersion: z
+      .string()
+      .regex(/^sha256:[a-f0-9]{64}$/u)
+      .optional(),
+  }),
+);
 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 type ModelCredentialReadinessV1 = z.infer<typeof ModelCredentialReadinessV1>;
+
+export const ModelAvailabilityV1 = /* @__PURE__ */ defineModelContractSchema(() =>
+  z.object({
+    status: z.enum(["available", "unavailable", "degraded", "unknown"]),
+    selectable: z.boolean(),
+    reason: z
+      .enum([
+        "missing_credential",
+        "needs_reauth",
+        "credential_not_ready",
+        "not_entitled",
+        "provider_unhealthy",
+        "policy_blocked",
+        "unsupported",
+      ])
+      .nullable(),
+    checkedAt: z.string().datetime().nullable(),
+  }),
+);
+export type ModelAvailabilityV1 = z.infer<typeof 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 type WorkspaceModelCatalogResponse = z.infer<typeof WorkspaceModelCatalogResponse>;
+
 /**
  * Exact public HTTP protocol revision spoken by this release train.
  *
@@ -7338,46 +8474,48 @@ export type ClientModel = z.infer<typeof ClientModel>;
 export const OPENGENI_API_CONTRACT_REVISION = "2026-07-turn-instructions-v1" as const;
 export const OPENGENI_API_CONTRACT_HEADER = "x-opengeni-api-contract" as const;
 
-export const ClientConfig = z.object({
-  deploymentRevision: z.string(),
-  apiContractRevision: z.literal(OPENGENI_API_CONTRACT_REVISION),
-  // Release-train version of the server (absent on dev/source builds). The
-  // compatibility policy lives in docs/architecture.md — clients within the
-  // same major are supported; evolution is additive within a major.
-  serverVersion: z.string().optional(),
-  defaultModel: z.string(),
-  allowedModels: z.array(z.string()).min(1),
-  // Richer model list (provider-grouped) for the picker. Defaults to [] for
-  // back-compat: callers that only read allowedModels are unaffected.
-  models: z.array(ClientModel).default([]),
-  defaultReasoningEffort: ReasoningEffort,
-  allowedReasoningEfforts: z.array(ReasoningEffort).min(1),
-  mcpServers: z
-    .array(
-      z.object({
-        id: z.string(),
-        name: z.string(),
-      }),
-    )
-    .default([]),
-  fileUploads: z.object({
-    enabled: z.boolean(),
-    maxSizeBytes: z.number().int().positive(),
+export const ClientConfig = /* @__PURE__ */ defineModelContractSchema(() =>
+  z.object({
+    deploymentRevision: z.string(),
+    apiContractRevision: z.literal(OPENGENI_API_CONTRACT_REVISION),
+    // Release-train version of the server (absent on dev/source builds). The
+    // compatibility policy lives in docs/architecture.md — clients within the
+    // same major are supported; evolution is additive within a major.
+    serverVersion: z.string().optional(),
+    defaultModel: z.string(),
+    allowedModels: z.array(z.string()).min(1),
+    // Richer model list (provider-grouped) for the picker. Defaults to [] for
+    // back-compat: callers that only read allowedModels are unaffected.
+    models: z.array(ClientModel).default([]),
+    defaultReasoningEffort: ReasoningEffort,
+    allowedReasoningEfforts: z.array(ReasoningEffort).min(1),
+    mcpServers: z
+      .array(
+        z.object({
+          id: z.string(),
+          name: z.string(),
+        }),
+      )
+      .default([]),
+    fileUploads: z.object({
+      enabled: z.boolean(),
+      maxSizeBytes: z.number().int().positive(),
+    }),
+    productAccessMode: ProductAccessMode,
+    auth: ClientAuthConfig.default({ mode: "none" }),
+    // Server-wide hint: does this deployment support Channel-A structured services
+    // at all (P4.4). Per-session availability is negotiated on /stream-capabilities
+    // (it depends on the session's pinned backend); this is the coarse on/off the
+    // client uses to decide whether to even attempt the fs/git/terminal panels.
+    structuredServices: z
+      .object({
+        fileSystem: z.boolean(),
+        git: z.boolean(),
+        terminalEvents: z.boolean(),
+      })
+      .default({ fileSystem: false, git: false, terminalEvents: false }),
   }),
-  productAccessMode: ProductAccessMode,
-  auth: ClientAuthConfig.default({ mode: "none" }),
-  // Server-wide hint: does this deployment support Channel-A structured services
-  // at all (P4.4). Per-session availability is negotiated on /stream-capabilities
-  // (it depends on the session's pinned backend); this is the coarse on/off the
-  // client uses to decide whether to even attempt the fs/git/terminal panels.
-  structuredServices: z
-    .object({
-      fileSystem: z.boolean(),
-      git: z.boolean(),
-      terminalEvents: z.boolean(),
-    })
-    .default({ fileSystem: false, git: false, terminalEvents: false }),
-});
+);
 export type ClientConfig = z.infer<typeof ClientConfig>;
 
 function base64UrlEncode(value: string): string {
@@ -7454,3 +8592,5 @@ export function evaluateWorkspaceModelPolicy(
   }
   return { allowed: true };
 }
+
+export * from "./codex-fleet-policy";