Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
58.0 KB
Raw Blame
'use client'

import React, { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'
import { validateDisplayField } from '@clerum/display-field'
import { SubscriptionCapabilityNotice } from '@components/SubscriptionCapabilityNotice'
import { useSubscriptionCapabilities } from '@lib/hooks/useSubscriptionCapabilities'
import { CreateFlowPanel } from '@/components/CreateFlowPanel'
import { CreateStepFlow } from '@/components/CreateStepFlow'
import { LlmProviderConfig } from '@/components/LlmProviderConfig'
import { LlmSecretSelect } from '@/components/LlmSecretSelect'
import { SelectionDropdown } from '@/components/SelectionDropdown'
import { useToast } from '@/components/Toast'
import { IconAlertTriangle, IconCheck, IconX } from '@/components/icons'
import { Button, CheckboxField, Field, TextInput } from '@/components/ui'
import {
  apiSend,
  getAdminTeams,
  getAdminUsers,
  updateAgentTeams,
  updateAgentUsers,
} from '@/lib/api'
import { cn } from '@/lib/cn'
import {
  CODEX_UNASSIGNED_CONNECTION_KEY,
  type CodexSubscriptionConnectionView,
  isAssignableCodexGrant,
  listCodexConnectionModels,
  listCodexSubscriptionConnections,
} from '@/lib/codexSubscription'
import { isDisabledCapabilityError } from '@/lib/codexSubscriptionFeature'
import {
  type GrokSubscriptionConnectionView,
  isAssignableGrokGrant,
  listGrokConnectionModels,
  listGrokSubscriptionConnections,
} from '@/lib/grokSubscription'
import { useLlmAllowedModels } from '@/lib/hooks/useLlmAllowedModels'
import { getAgentNameError } from '@/lib/k8sValidation'
import {
  GROK_SUBSCRIPTION_PROVIDER,
  type HostAllowedModel,
  type LlmPolicy,
  type LlmProvider,
  buildAllowedModelsSpec,
  constrainModelOptions,
  createEmptyLlmKeyDraft,
  getActiveCredentialKeys,
  getModelOptions,
  getProviderLabel,
  getProvidersWithCompleteCredentials,
  isOauthBrokerProvider,
  isProviderUsable,
  llmChainRequiresSecret,
  offeredCodexModelNames,
  projectCredentialDraft,
  resolveCodexGrantModel,
  resolveDefaultModel,
  validateLlmSecretData,
} from '@/lib/llm'
import { credentialSelectValue, parseCredentialSelect } from '@/lib/llmCredentialSelect'
import { createPrivateContext } from '@/lib/privateContext'
import { toKebabCase, toKebabInput } from '@/lib/string'
import {
  HOST_NAMESPACE,
  HOST_SECRET_LABEL_KEY,
  HOST_SECRET_LABEL_VALUE,
  STEPS,
  STEP_DETAILS,
} from './constants'
import type { CreatedResource, HostWizardProps, HostWizardValidationState } from './types'

// Asymmetric save gate (spec Topic 1b): the PRIMARY provider must be usable —
// its required credential slot(s) filled — before create is allowed. Fallbacks
// are optional and only warn, so they never enter this gate.
function primaryCredentialUsable(provider: LlmProvider, draft: Record<string, string>): boolean {
  return isProviderUsable(provider, key => (draft[key] ?? '').trim().length > 0)
}

// TASK-231: human label for a connector's transport, shown on the step-4 cards
// so the grid reads as a catalog instead of a bare name list. Falls back to
// "Connector" when the spec carries no recognizable transport (legacy CRs).
function mcpConnectorMeta(spec: Record<string, unknown> | undefined): string {
  const transport = spec?.transport
  const type =
    transport && typeof transport === 'object' && !Array.isArray(transport)
      ? String((transport as { type?: unknown }).type || '')
      : ''
  if (type === 'stdio') return 'Connector · local (stdio)'
  if (type === 'sse') return 'Connector · HTTP (SSE)'
  if (type === 'streamableHttp') return 'Connector · HTTP'
  return 'Connector'
}

// The DELETE path for one tracked sibling. The server fixes each resource's
// namespace (secrets → config.secretsNamespace; hosts/contexts/channels →
// their configured namespace), so — exactly like the SecretsTable /
// CommunicationChannelsTable / deleteContext call-sites — no namespace query is
// sent. Deleting a communicationchannel also removes its credentials Secret
// server-side, so a channel's credential Secret is never tracked or deleted
// separately here.
function compensationPath(entry: CreatedResource): string {
  const encoded = encodeURIComponent(entry.name)
  switch (entry.kind) {
    case 'secret':
      return `/api/v1/admin/secrets/${encoded}`
    case 'context':
      return `/api/v1/admin/contexts/${encoded}`
    case 'communication-channel':
      return `/api/v1/admin/communication-channels/${encoded}`
  }
}

// Inverse-order (channel → context → secret) best-effort rollback of the
// siblings THIS run created before the Host create failed, so a failed create
// never leaves an orphaned secret/context/channel behind. Best-effort: each
// DELETE is independent, a 404 is success (idempotent — the resource is already
// gone), and NO failure is re-thrown — a rollback error must never mask the
// original create error the caller is about to surface. The server performs a
// direct delete with no referential-integrity/finalizer coupling between the
// siblings, so inverse order is for tidiness, not correctness.
async function compensateCreated(created: CreatedResource[]): Promise<void> {
  for (let i = created.length - 1; i >= 0; i -= 1) {
    const entry = created[i]
    try {
      await apiSend('DELETE', compensationPath(entry))
    } catch (err) {
      console.warn(
        `HostWizard: best-effort rollback of ${entry.kind} "${entry.name}" failed after a create error`,
        err
      )
    }
  }
}

// A create-only POST, with the 409 disambiguation done HERE — at the create
// site — never in the shared submitAll catch. This is deliberate: only a POST to
// a create-only /admin/{secrets,contexts,communication-channels,hosts} endpoint
// can turn a code-less 409 into an UNAMBIGUOUS AlreadyExists name collision. The
// grant endpoints (409 `deleted_agent_history_limit_exceeded`) share the
// top-level catch but can NEVER reach here, so their messages are preserved.
//
// The two 409 shapes from THESE endpoints (V-1):
//   - WITH a body `code` (context_crd_outdated / communication_channel_crd_outdated)
//     → a CRD-outdated response, NOT a collision. formatApiError already set
//       e.message to the server's human `error` text, so re-throw e untouched.
//   - WITHOUT a body `code` → apiserver AlreadyExists. The create-only POST
//     refused to overwrite a foreign resource; replace the raw K8s text with the
//     friendly, per-resource `collisionMessage`.
// Discriminate on `body.code` (the field INSIDE the JSON body), never on the
// client's `.code` (which formatApiError sets from `body.error`, the message).
// Any non-409 error is re-thrown verbatim.
class ResourceNameCollisionError extends Error {
  constructor(message: string) {
    super(message)
    this.name = 'ResourceNameCollisionError'
  }
}

async function createOrThrow(path: string, body: unknown, collisionMessage: string): Promise<void> {
  try {
    await apiSend('POST', path, body)
  } catch (e) {
    if (e instanceof Error && (e as Error & { status?: number }).status === 409) {
      const errBody = (e as Error & { body?: { code?: unknown } }).body
      const hasCode = typeof errBody?.code === 'string' && errBody.code.length > 0
      // Code-less 409 from a create-only POST = unambiguous name collision.
      if (!hasCode) throw new ResourceNameCollisionError(collisionMessage)
      // Coded 409 (CRD-outdated) keeps the server's own message (e.message).
    }
    throw e
  }
}

// Step 0 collects a free-text display name (`spec.host`) and derives the
// immutable identifier (`metadata.name`) from it. Two validations apply:
//  - the DISPLAY name passes the shared display-field rule (control chars +
//    trimmed length, D4: same validator as control-api's write gate — the field
//    label is passed in so the issue text reads as wizard copy);
//  - the DERIVED slug passes the RFC1123 agent-name rule (3–63 chars, lowercase
//    alphanumerics + hyphens), because the slug is what reaches metadata.name.
function agentStepError(displayName: string): string {
  if (!displayName.trim()) return 'Agent name is required.'
  const displayIssue = validateDisplayField(displayName, 'Agent name')
  if (displayIssue) return displayIssue.message
  const slug = toKebabCase(displayName)
  // A non-empty name whose characters all strip out (e.g. "###" or a name with
  // no Latin letters/digits) derives an empty slug — a distinct problem from a
  // missing name, so it gets distinct copy instead of "is required".
  if (!slug) return 'Add at least one letter or number so an identifier can be derived.'
  return getAgentNameError(slug)
}

function isStepValid(stepIndex: number, state: HostWizardValidationState): boolean {
  if (stepIndex === 0)
    return state.hostName.trim().length > 0 && agentStepError(state.hostName) === ''
  if (stepIndex === 1) {
    if (!state.modelName.trim()) return false
    if (
      isOauthBrokerProvider(state.provider) &&
      (!state.connectionRef.trim() ||
        state.connectionRef.trim() === CODEX_UNASSIGNED_CONNECTION_KEY ||
        // An empty picker offers nothing, so a model kept from an earlier
        // catalog or connection cannot pass.
        !state.brokerModelOptions.includes(state.modelName.trim()))
    ) {
      return false
    }
    // Broker-only chains need the grant in the shared LLM Secret picker. Any
    // static primary/fallback still requires the exact credential slots.
    if (!llmChainRequiresSecret(state.provider, state.llmPolicy?.fallbacks)) {
      return (
        isOauthBrokerProvider(state.provider) &&
        parseCredentialSelect(state.existingSecret).kind === 'subscription'
      )
    }
    // New secret: the PRIMARY provider must be usable (asymmetric gate — a
    // fallback missing its key only warns). Cross-slot mistakes (half Bedrock
    // pair, malformed Vertex JSON) anywhere still block. Existing secret: the
    // wizard can't introspect its keys, so a selection is the only gate.
    // Validate only the ACTIVE-domain keys — a value typed for a provider whose
    // block later unmounted (primary switched, or a fallback removed) must not
    // block (e.g. a lone Bedrock access key left behind by a removed fallback).
    const projectedDraft = projectCredentialDraft(
      state.llmKeyDraft,
      getActiveCredentialKeys(state.provider, state.llmPolicy)
    )
    const hasValidSecret =
      state.secretMode === 'existing'
        ? isOauthBrokerProvider(state.provider)
          ? state.existingLlmSecret.trim().length > 0
          : parseCredentialSelect(state.existingSecret).kind === 'secret'
        : toKebabCase(state.newSecretName).length > 0 &&
          primaryCredentialUsable(state.provider, state.llmKeyDraft) &&
          validateLlmSecretData(projectedDraft).length === 0
    return hasValidSecret
  }
  if (stepIndex === 2 || stepIndex === 3) return true
  return false
}

export function HostWizard({
  mcpServers,
  existingSecrets,
  mode = 'modal',
  onCreated,
  onClose,
  pageHeader,
}: HostWizardProps) {
  const { showToast } = useToast()
  const [step, setStep] = useState(0)
  const [busy, setBusy] = useState(false)
  const subscriptionCapabilities = useSubscriptionCapabilities({ enabled: step === 1 })
  const codexEnabled =
    subscriptionCapabilities.capabilities?.providers['codex-subscription'].enabled ?? false
  const grokEnabled =
    subscriptionCapabilities.capabilities?.providers['grok-subscription'].enabled ?? false
  const [error, setError] = useState('')
  const [directoryLoading, setDirectoryLoading] = useState(false)
  const [directoryLoadError, setDirectoryLoadError] = useState('')
  const mountedRef = useRef(true)

  useEffect(() => {
    mountedRef.current = true
    return () => {
      mountedRef.current = false
    }
  }, [])

  const [hostName, setHostName] = useState('')
  const hostNamespace = HOST_NAMESPACE
  // TASK-230: the operator types a free-text display name; the immutable
  // metadata.name slug is derived from it (shown live under the field) instead
  // of being force-lowercased into the input while typing.
  const derivedHostName = toKebabCase(hostName)
  const agentNameError = agentStepError(hostName)
  // Stable id for the slug-hint note so the input can point at it with
  // aria-describedby (the note carries the error copy when invalid).
  const slugNoteId = useId()

  const [selectedMcp, setSelectedMcp] = useState<string[]>([])

  // Reuse an existing shared Secret by default. Creating an agent-specific Secret
  // remains available when the operator explicitly chooses New credential.
  const [secretMode, setSecretMode] = useState<'existing' | 'new'>('existing')
  const [existingSecret, setExistingSecret] = useState('')
  const [existingLlmSecret, setExistingLlmSecret] = useState('')
  const [newSecretName, setNewSecretName] = useState('')
  const [secretNameTouched, setSecretNameTouched] = useState(false)
  const [llmKeyDraft, setLlmKeyDraft] = useState<Record<string, string>>(createEmptyLlmKeyDraft)
  const [llmPolicy, setLlmPolicy] = useState<LlmPolicy | undefined>(undefined)
  // Per-host model allowlist subset (spec.allowedModels, Topic 3a). Empty = the
  // host offers the full global allowlist per provider (back-compat default).
  const [allowedModels, setAllowedModels] = useState<HostAllowedModel[]>([])

  const [provider, setProvider] = useState<LlmProvider>('openai')
  // Model list is the operator allowlist (enabled only), loaded async. Start
  // empty; an effect selects the default once the allowlist arrives. No
  // hardcoded fallback list (spec R4.5.1).
  const {
    models: allowedCatalog,
    loading: modelsLoading,
    error: modelsError,
  } = useLlmAllowedModels()
  const [modelName, setModelName] = useState('')
  const [connectionRef, setConnectionRef] = useState(CODEX_UNASSIGNED_CONNECTION_KEY)
  const [codexModels, setCodexModels] = useState<string[]>([])
  const [codexConnections, setCodexConnections] = useState<CodexSubscriptionConnectionView[]>([])
  const [grokModels, setGrokModels] = useState<string[]>([])
  const [grokConnections, setGrokConnections] = useState<GrokSubscriptionConnectionView[]>([])
  const [grantInventoryError, setGrantInventoryError] = useState('')
  const [grantCatalogError, setGrantCatalogError] = useState('')
  const [grantInventoryLoading, setGrantInventoryLoading] = useState(false)
  const [inventoryRetryNonce, setInventoryRetryNonce] = useState(0)
  const [stateless, setStateless] = useState(false)
  const [users, setUsers] = useState<
    Array<{ id: string; email: string; name: string | null; displayName: string | null }>
  >([])
  const [teams, setTeams] = useState<Array<{ id: string; name: string; memberCount: number }>>([])
  const [selectedUserIds, setSelectedUserIds] = useState<string[]>([])
  const [selectedTeamIds, setSelectedTeamIds] = useState<string[]>([])
  const [accessTab, setAccessTab] = useState<'members' | 'teams'>('members')

  const availableMcp = useMemo(
    () =>
      mcpServers
        .map(m => {
          const name = m.metadata?.name
          if (!name) return null
          return { name, meta: mcpConnectorMeta(m.spec) }
        })
        .filter((v): v is { name: string; meta: string } => Boolean(v))
        .sort((left, right) => left.name.localeCompare(right.name)),
    [mcpServers]
  )

  const secretOptions = useMemo(
    () => [
      ...existingSecrets
        .map(secret => {
          const name = secret.name || secret.metadata?.name
          if (!name) return null
          const providers = Array.isArray(secret.keys)
            ? getProvidersWithCompleteCredentials(secret.keys)
            : null
          const providerSummary =
            providers === null
              ? 'Provider keys unavailable'
              : providers.length > 0
                ? `Providers: ${providers.map(getProviderLabel).join(', ')}`
                : 'No recognized provider credentials'
          return {
            group: 'API keys',
            value: name,
            label: name,
            meta: providerSummary,
            providers:
              providers && providers.length > 0
                ? providers.map(id => ({ id, label: getProviderLabel(id) }))
                : undefined,
          }
        })
        .filter(option => option !== null)
        .sort((left, right) => left.value.localeCompare(right.value)),
      ...codexConnections.filter(isAssignableCodexGrant).map(row => ({
        group: 'ChatGPT subscriptions',
        value: credentialSelectValue('', row.connectionKey),
        label: row.displayName || row.connectionKey,
        meta: 'ChatGPT subscription',
        providers: [{ id: 'codex-subscription', label: 'ChatGPT Subscription' }],
      })),
      ...grokConnections.filter(isAssignableGrokGrant).map(row => ({
        group: 'Grok subscriptions',
        value: credentialSelectValue('', row.connectionKey, GROK_SUBSCRIPTION_PROVIDER),
        label: row.displayName || row.connectionKey,
        meta: 'Grok subscription',
        providers: [{ id: GROK_SUBSCRIPTION_PROVIDER, label: 'xAI Grok Subscription' }],
      })),
    ],
    [codexConnections, grokConnections, existingSecrets]
  )
  const apiKeyOptions = useMemo(
    () => secretOptions.filter(option => option.group === 'API keys'),
    [secretOptions]
  )
  const catalogForEditor = useMemo(() => {
    if (provider === 'codex-subscription') {
      const others = allowedCatalog.filter(row => row.provider !== 'codex-subscription')
      if (codexModels.length === 0) return others
      return [
        ...others,
        ...codexModels.map(model => ({
          id: `codex:${model}`,
          provider: 'codex-subscription',
          model,
          vendor: 'OpenAI',
          display_name: model,
          context_window_tokens: null,
          enabled: true,
          source: 'discovery' as const,
          stale: false,
        })),
      ]
    }
    if (provider === GROK_SUBSCRIPTION_PROVIDER) {
      const others = allowedCatalog.filter(row => row.provider !== GROK_SUBSCRIPTION_PROVIDER)
      if (grokModels.length === 0) return others
      return [
        ...others,
        ...grokModels.map(model => ({
          id: `grok:${model}`,
          provider: GROK_SUBSCRIPTION_PROVIDER,
          model,
          vendor: 'xAI',
          display_name: model,
          context_window_tokens: null,
          enabled: true,
          source: 'discovery' as const,
          stale: false,
        })),
      ]
    }
    return allowedCatalog
  }, [allowedCatalog, provider, codexModels, grokModels])
  const providerModelOptions = useMemo(
    () => getModelOptions(catalogForEditor, provider),
    [catalogForEditor, provider]
  )
  const brokerModelOptions = useMemo(
    () =>
      isOauthBrokerProvider(provider)
        ? constrainModelOptions(catalogForEditor, allowedModels, provider)
        : [],
    [allowedModels, catalogForEditor, provider]
  )
  const chainRequiresSecret = llmChainRequiresSecret(provider, llmPolicy?.fallbacks)
  const handleExistingSecretChange = useCallback(
    (secretName: string) => {
      setExistingSecret(secretName)
      const parsed = parseCredentialSelect(secretName)
      if (parsed.kind === 'subscription') {
        setConnectionRef(parsed.connectionKey)
        setProvider(parsed.provider)
        setModelName('')
        return
      }
      setConnectionRef(CODEX_UNASSIGNED_CONNECTION_KEY)
      setCodexModels([])
      setGrokModels([])
      const selectedSecret = existingSecrets.find(
        secret => (secret.name || secret.metadata?.name) === secretName
      )
      if (!Array.isArray(selectedSecret?.keys)) return
      const [linkedProvider] = getProvidersWithCompleteCredentials(selectedSecret.keys)
      if (!linkedProvider) return
      const nextProvider = linkedProvider === 'codex-subscription' ? 'openai' : linkedProvider
      setProvider(nextProvider)
      setModelName(resolveDefaultModel(nextProvider, getModelOptions(allowedCatalog, nextProvider)))
    },
    [allowedCatalog, existingSecrets]
  )
  useEffect(() => {
    if (step !== 1 || !subscriptionCapabilities.capabilities) {
      setGrantInventoryError('')
      setGrantInventoryLoading(false)
      return
    }
    const controller = new AbortController()
    setGrantInventoryLoading(true)
    const requests = [
      codexEnabled
        ? listCodexSubscriptionConnections({ signal: controller.signal })
        : Promise.resolve([]),
      ...(grokEnabled ? [listGrokSubscriptionConnections({ signal: controller.signal })] : []),
    ]
    Promise.allSettled(requests)
      .then(([codexResult, grokResult]) => {
        if (controller.signal.aborted) return
        if (codexResult.status === 'fulfilled') setCodexConnections(codexResult.value)
        if (grokResult?.status === 'fulfilled') setGrokConnections(grokResult.value)
        setGrantInventoryError('')
        const failure = [codexResult, grokResult].find(
          result => result?.status === 'rejected' && !isDisabledCapabilityError(result.reason)
        )
        if (failure?.status === 'rejected') throw failure.reason
      })
      .catch(err => {
        if (controller.signal.aborted || isDisabledCapabilityError(err)) return
        setGrantInventoryError(
          err instanceof Error && err.message ? err.message : 'Could not load subscription options'
        )
      })
      .finally(() => {
        if (!controller.signal.aborted) setGrantInventoryLoading(false)
      })
    return () => controller.abort()
  }, [codexEnabled, grokEnabled, inventoryRetryNonce, step, subscriptionCapabilities.capabilities])
  useEffect(() => {
    if (step !== 1) return
    if (!connectionRef.trim() || connectionRef === CODEX_UNASSIGNED_CONNECTION_KEY) {
      setCodexModels([])
      setGrokModels([])
      setGrantCatalogError('')
      return
    }
    setGrantCatalogError('')
    // A catalog belongs to one connection: drop the previous connection's
    // models before this load so they can never be offered under this ref.
    setCodexModels([])
    setGrokModels([])
    const controller = new AbortController()
    // The retry nonce only re-runs this load. A catalog recovered after a 429
    // is already cached; bypassing it would spend a second read in the window.
    if (provider === GROK_SUBSCRIPTION_PROVIDER) {
      void listGrokConnectionModels(connectionRef, { signal: controller.signal })
        .then(models => {
          if (!controller.signal.aborted) setGrokModels(offeredCodexModelNames(models))
        })
        .catch(err => {
          if (!controller.signal.aborted) {
            setGrantCatalogError(
              err instanceof Error ? err.message : 'Could not load Grok grant models'
            )
          }
        })
      return () => {
        controller.abort()
      }
    }
    void listCodexConnectionModels(connectionRef, { signal: controller.signal })
      .then(models => {
        if (!controller.signal.aborted) setCodexModels(offeredCodexModelNames(models))
      })
      .catch(err => {
        if (!controller.signal.aborted) {
          setGrantCatalogError(
            err instanceof Error ? err.message : 'Could not load ChatGPT grant models'
          )
        }
      })
    return () => {
      controller.abort()
    }
  }, [connectionRef, inventoryRetryNonce, provider, step])
  // Keep the selected model valid for the current provider's enabled models:
  // seed the default once the allowlist loads, and re-default if a provider
  // switch left the model out of range.
  useEffect(() => {
    if (modelsLoading) return
    if (isOauthBrokerProvider(provider)) {
      if (brokerModelOptions.length === 0) return
      const grant = (
        provider === GROK_SUBSCRIPTION_PROVIDER ? grokConnections : codexConnections
      ).find(row => row.connectionKey === connectionRef)
      const next = resolveCodexGrantModel(modelName, brokerModelOptions, grant?.defaultModel)
      if (next !== modelName) setModelName(next)
      return
    }
    if (!providerModelOptions.includes(modelName)) {
      setModelName(resolveDefaultModel(provider, providerModelOptions))
    }
    // Intentionally omit modelName: this reconciles the picker to the options.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [brokerModelOptions, modelsLoading, provider, providerModelOptions])

  // Auto-derive the new Secret name from the agent name ("this agent's
  // credentials") until the operator edits it, so naming a Kubernetes Secret is
  // never a required step (spec Topic 1b R4). The field stays visible + editable.
  useEffect(() => {
    if (secretNameTouched) return
    const base = toKebabCase(hostName)
    setNewSecretName(base ? `${base}-llm` : '')
  }, [hostName, secretNameTouched])

  // Keys feeding the fallback credentialSlot dropdown in create: the extra slots
  // the operator typed a value for, plus any slot a fallback already points at.
  const llmSecretKeys = useMemo(() => {
    const keys = new Set<string>()
    for (const [key, value] of Object.entries(llmKeyDraft)) {
      if (value.trim().length > 0) keys.add(key)
    }
    for (const fallback of llmPolicy?.fallbacks ?? []) {
      if (fallback.credentialSlot) keys.add(fallback.credentialSlot)
    }
    return Array.from(keys)
  }, [llmKeyDraft, llmPolicy])
  const memberAccessOptions = useMemo(
    () =>
      users.map(user => ({
        value: user.id,
        label: user.displayName || user.name || user.email,
        description: user.email || 'Member',
      })),
    [users]
  )
  const teamAccessOptions = useMemo(
    () =>
      teams.map(team => ({
        value: team.id,
        label: team.name,
        description: `${team.memberCount} ${team.memberCount === 1 ? 'member' : 'members'}`,
      })),
    [teams]
  )

  const validationState = useMemo<HostWizardValidationState>(
    () => ({
      hostName,
      secretMode,
      existingSecret,
      existingLlmSecret,
      newSecretName,
      llmKeyDraft,
      llmPolicy,
      provider,
      modelName,
      connectionRef,
      brokerModelOptions,
    }),
    [
      hostName,
      secretMode,
      existingSecret,
      existingLlmSecret,
      newSecretName,
      llmKeyDraft,
      llmPolicy,
      provider,
      modelName,
      connectionRef,
      brokerModelOptions,
    ]
  )

  const canNext = useMemo(() => isStepValid(step, validationState), [step, validationState])

  const loadDirectory = useCallback(async () => {
    setDirectoryLoading(true)
    setDirectoryLoadError('')
    setError('')
    try {
      const [usersData, teamsData] = await Promise.all([getAdminUsers(''), getAdminTeams()])
      if (!mountedRef.current) return
      setUsers(Array.isArray(usersData.items) ? usersData.items : [])
      setTeams(Array.isArray(teamsData.items) ? teamsData.items : [])
    } catch (e) {
      if (!mountedRef.current) return
      const message =
        e instanceof Error
          ? `Failed to load users/teams: ${e.message}. You may not be able to grant access from this wizard — retry or check your session.`
          : 'Failed to load users/teams. You may not be able to grant access from this wizard.'
      setDirectoryLoadError(message)
      setError(message)
    } finally {
      if (mountedRef.current) setDirectoryLoading(false)
    }
  }, [])

  useEffect(() => {
    void loadDirectory()
  }, [loadDirectory])

  const canJumpToStep = useMemo(
    () => (targetStep: number) => {
      if (targetStep <= step) return true
      for (let i = 0; i < targetStep; i += 1) {
        if (!isStepValid(i, validationState)) {
          return false
        }
      }
      return true
    },
    [step, validationState]
  )

  const validationMessage = useMemo(() => {
    if (step === 0) {
      const agentNameError = agentStepError(hostName)
      if (agentNameError) return agentNameError
    }
    if (step === 1 && !modelName.trim()) return 'Model name is required.'
    if (step === 1 && secretMode === 'existing' && !existingSecret.trim())
      return 'Select an existing LLM Secret.'
    if (
      step === 1 &&
      secretMode === 'existing' &&
      isOauthBrokerProvider(provider) &&
      chainRequiresSecret &&
      !existingLlmSecret.trim()
    ) {
      return 'Select an existing LLM Secret.'
    }
    if (step === 1 && secretMode === 'new' && !toKebabCase(newSecretName)) {
      return 'For a new LLM Secret, set a name.'
    }
    if (step === 1 && secretMode === 'new' && !primaryCredentialUsable(provider, llmKeyDraft)) {
      return `Add the ${getProviderLabel(provider)} credential for the primary model.`
    }
    if (step === 1 && secretMode === 'new') {
      const projected = projectCredentialDraft(
        llmKeyDraft,
        getActiveCredentialKeys(provider, llmPolicy)
      )
      const slotErrors = validateLlmSecretData(projected)
      if (slotErrors.length > 0) return slotErrors[0]
    }
    return ''
  }, [
    step,
    hostName,
    secretMode,
    existingSecret,
    existingLlmSecret,
    newSecretName,
    llmKeyDraft,
    llmPolicy,
    provider,
    modelName,
    chainRequiresSecret,
  ])

  function resetForm() {
    setStep(0)
    setError('')

    setHostName('')
    setSelectedMcp([])
    setSecretMode('existing')
    setExistingSecret('')
    setExistingLlmSecret('')
    setNewSecretName('')
    setSecretNameTouched(false)
    setLlmKeyDraft(createEmptyLlmKeyDraft())
    setLlmPolicy(undefined)
    setAllowedModels([])
    setProvider('openai')
    setModelName(resolveDefaultModel('openai', getModelOptions(allowedCatalog, 'openai')))
    setConnectionRef(CODEX_UNASSIGNED_CONNECTION_KEY)
    setCodexModels([])
    setStateless(false)
    setSelectedUserIds([])
    setSelectedTeamIds([])
    setAccessTab('members')
  }

  useEffect(() => {
    resetForm()
  }, [])

  function toggleMcp(name: string) {
    setSelectedMcp(prev => {
      const set = new Set(prev)
      if (set.has(name)) set.delete(name)
      else set.add(name)
      return Array.from(set)
    })
  }

  async function submitAll() {
    setBusy(true)
    setError('')
    // Rollback ledger for the create-only seam: every sibling THIS run POSTs
    // successfully is appended here so a later failure (before the Host exists)
    // can inverse-compensate it. Only successful POSTs of this execution are
    // tracked — never inferred from slug/label. Declared outside the try so the
    // catch can read it.
    const created: CreatedResource[] = []
    let hostCreated = false
    try {
      const normalizedHostName = toKebabCase(hostName)
      const normalizedSecretName = toKebabCase(newSecretName)

      if (chainRequiresSecret && secretMode === 'new') {
        // Project the draft onto the active domain before writing: only the
        // primary provider's slots ∪ each fallback's effective slot(s) reach the
        // Secret — a key left behind by a since-removed provider is dropped, not
        // written as an orphan (spec Topic 1b).
        const stringData = projectCredentialDraft(
          llmKeyDraft,
          getActiveCredentialKeys(provider, llmPolicy)
        )
        // Slot-aware validation (spec R4.5.3), mirrored server-side.
        const slotErrors = validateLlmSecretData(stringData)
        if (slotErrors.length > 0) {
          throw new Error(slotErrors[0])
        }
        // Create-only POST (R5-C1/R5-B1): a name collision must 409 AlreadyExists
        // server-side, never silently overwrite a foreign Secret via a PUT. The
        // 409 → friendly message translation is scoped to createOrThrow.
        await createOrThrow(
          '/api/v1/admin/secrets',
          {
            name: normalizedSecretName,
            namespace: hostNamespace,
            labels: {
              [HOST_SECRET_LABEL_KEY]: HOST_SECRET_LABEL_VALUE,
            },
            stringData,
          },
          `A credential secret named "${normalizedSecretName}" already exists — choose another name.`
        )
        // The host's own LLM Secret (${slug}-llm). Tracked so a later failure
        // rolls it back explicitly by name.
        created.push({ kind: 'secret', name: normalizedSecretName })
      }

      // Every agent gets a private implementation context. The context name is
      // intentionally generated here instead of being exposed as a wizard
      // field; the agent still needs a contextRef for its runtime contract.
      const generatedContextName = await createPrivateContext(
        {
          subject: normalizedHostName,
          description: `Connector context for agent ${normalizedHostName}`,
          mcpServers: Array.from(new Set(selectedMcp)),
        },
        'We couldn’t finish setting up this agent’s connectors — please try again.'
      )
      created.push({ kind: 'context', name: generatedContextName })

      // Effective per-host model subset (Topic 3a): prune the draft to the
      // providers actually in this host's domain (primary + fallbacks), then
      // collapse unrestricted/all-selected providers via buildAllowedModelsSpec.
      const activeAllowedProviders = new Set<string>([
        provider,
        ...(llmPolicy?.fallbacks ?? []).map(fallback => fallback.provider),
      ])
      const allowedModelsSpec = buildAllowedModelsSpec(
        allowedModels.filter(entry => activeAllowedProviders.has(entry.provider)),
        allowedCatalog
      )

      const resolvedSecretRef = !chainRequiresSecret
        ? ''
        : secretMode === 'new'
          ? normalizedSecretName
          : isOauthBrokerProvider(provider)
            ? existingLlmSecret.trim()
            : parseCredentialSelect(existingSecret).kind === 'secret'
              ? existingSecret
              : ''

      const hostSpec: Record<string, unknown> = {
        // Display name: the free text the operator typed (falls back to the
        // slug only when the trimmed name is somehow empty). The slug lives in
        // metadata.name below — the two are intentionally distinct now.
        host: hostName.trim() || normalizedHostName,
        contextRef: generatedContextName,
        ...(resolvedSecretRef ? { secretRef: resolvedSecretRef } : {}),
        channels: [],
        model: {
          provider,
          name: modelName,
          ...(isOauthBrokerProvider(provider)
            ? { connectionRef: connectionRef.trim() || CODEX_UNASSIGNED_CONNECTION_KEY }
            : {}),
        },
        // Opt-in fallback policy (spec §3-R5): only set when at least one
        // fallback is configured, so a Host without fallbacks behaves as today.
        ...(llmPolicy && llmPolicy.fallbacks.length > 0 ? { llmPolicy } : {}),
        // Per-host model allowlist subset (spec Topic 3a): only set when the
        // operator restricted at least one provider to a genuine subset;
        // unrestricted providers are omitted so absent=all-global holds.
        ...(allowedModelsSpec.length > 0 ? { allowedModels: allowedModelsSpec } : {}),
        ...(stateless ? { lifecycle: { stateless: true } } : {}),
      }

      // Create-only POST (R5-C1/R5-B1): the Host is the seam boundary. A name
      // collision must 409 AlreadyExists rather than overwrite a foreign agent's
      // entire spec. Once this resolves, hostCreated flips the compensation off:
      // the siblings now belong to a real Host and must NOT be rolled back.
      await createOrThrow(
        '/api/v1/admin/hosts',
        {
          metadata: { name: normalizedHostName },
          spec: hostSpec,
        },
        `That agent name is already in use — choose another name.`
      )
      hostCreated = true

      // Associate authorized users and teams with the new agent in a single
      // atomic call each, rather than looping N×(GET+PUT) per selection.
      // Uses the agent-centric endpoints PUT /admin/agents/:name/users|teams.
      // These run AFTER hostCreated=true: if a grant fails, the Host + siblings
      // stay (V-7) — the operator retries grants from the agent detail page — so
      // no compensation runs for a grant failure.
      if (selectedUserIds.length > 0) {
        await updateAgentUsers(normalizedHostName, selectedUserIds)
      }
      if (selectedTeamIds.length > 0) {
        await updateAgentTeams(normalizedHostName, selectedTeamIds)
      }

      if (!mountedRef.current) return
      showToast('Agent created successfully.', { tone: 'success' })
      // TASK-229: hand the created agent's identifier back so the host page can
      // route straight to the new agent's detail view (name + route URL header).
      await onCreated({ name: normalizedHostName })
      if (!mountedRef.current) return
      onClose()
    } catch (e) {
      // The Host is the compensation boundary (V-7): if it never got created, the
      // siblings created before it are orphans — inverse-compensate them
      // best-effort. If it DID get created, leave everything (a grant failure is
      // recoverable from the agent detail page). Always await the rollback before
      // surfacing the error so a caller/test observes the terminal state.
      if (!hostCreated) {
        await compensateCreated(created)
      }
      // NO 409 remap here: each create-only POST already translated its OWN
      // collision inside createOrThrow. This catch also sees errors from paths
      // that run AFTER the Host — the grant calls (409
      // `deleted_agent_history_limit_exceeded`) — whose messages formatApiError
      // already produced; masking them as "already in use" told the operator a
      // collision that never happened. Preserve e.message verbatim.
      if (mountedRef.current) {
        setError(e instanceof Error ? e.message : 'Failed to create agent resources')
      }
    } finally {
      if (mountedRef.current) setBusy(false)
    }
  }

  const wizardBody = (
    <>
      {mode === 'modal' ? (
        <div className="cu-agent-dialog-head">
          <strong id="create-agent-title" className="cu-modal-panel__title">
            Create Agent
          </strong>
          <Button
            type="button"
            className="cu-btn--icon"
            onClick={onClose}
            disabled={busy}
            aria-label="Close"
            variant="ghost"
          >
            <IconX width={18} height={18} />
          </Button>
        </div>
      ) : null}

      <CreateStepFlow
        ariaLabel="Create agent steps"
        currentStep={step}
        onStepChange={setStep}
        canSelectStep={canJumpToStep}
        steps={STEP_DETAILS}
        stepLabels={STEPS}
        titleId={mode === 'page' ? 'create-agent-title' : 'create-agent-step-title'}
      >
        {step === 0 && (
          <div className="cu-form-stack cu-agent-form-stack">
            <Field
              description="The name members see. The identifier used in URLs is derived automatically."
              htmlFor="wizard-agent-name"
              label="Agent name"
              required
            >
              <span className="cu-agent-input-shell">
                <TextInput
                  id="wizard-agent-name"
                  value={hostName}
                  onChange={e => setHostName(e.target.value)}
                  placeholder="e.g. Support Bot"
                  autoFocus
                  aria-describedby={slugNoteId}
                  aria-invalid={hostName.trim() ? Boolean(agentNameError) : undefined}
                />
                {hostName.trim() ? (
                  agentNameError ? (
                    <span
                      className="cu-agent-input-shell__status cu-agent-input-shell__status--invalid"
                      aria-label={agentNameError}
                    >
                      <IconAlertTriangle width={16} height={16} />
                    </span>
                  ) : (
                    <span className="cu-agent-input-shell__status" aria-label="Valid agent name">
                      <IconCheck width={16} height={16} />
                    </span>
                  )
                ) : null}
              </span>
            </Field>
            <div
              className="cu-agent-slug-hint"
              data-state={hostName.trim() ? (agentNameError ? 'invalid' : 'ready') : 'empty'}
            >
              <span className="cu-agent-slug-hint__label">Identifier</span>
              <span className="cu-agent-slug-hint__value">{derivedHostName || 'agent-name'}</span>
              <span id={slugNoteId} className="cu-agent-slug-hint__note" aria-live="polite">
                {hostName.trim() && agentNameError
                  ? agentNameError
                  : 'Used in URLs, CLI, and grants. Lowercase letters, numbers, and hyphens.'}
              </span>
            </div>
            <div className="cu-agent-namespace">Namespace: {HOST_NAMESPACE}</div>
            <div className="cu-agent-access-section">
              <strong id="agent-type-label">Agent type</strong>
              <span className="cu-muted cu-agent-access-hint">
                Stateless agents suspend after the idle window and wake on demand. Communication
                channels currently keep an agent always-on, and desktop agents still require a
                stateful agent.
              </span>
              <div
                className="cu-agent-radio-group"
                role="radiogroup"
                aria-labelledby="agent-type-label"
              >
                <label className="cu-agent-radio cu-agent-radio--card">
                  <input
                    type="radio"
                    name="agent-type"
                    checked={!stateless}
                    onChange={() => setStateless(false)}
                  />
                  <span className="cu-agent-radio__copy">
                    <span className="cu-agent-radio__title">Stateful (always on)</span>
                    <span className="cu-agent-radio__description">
                      The agent keeps running continuously and responds immediately.
                    </span>
                  </span>
                </label>
                <label className="cu-agent-radio cu-agent-radio--card">
                  <input
                    type="radio"
                    name="agent-type"
                    checked={stateless}
                    onChange={() => setStateless(true)}
                  />
                  <span className="cu-agent-radio__copy">
                    <span className="cu-agent-radio__title">Stateless (suspends when idle)</span>
                    <span className="cu-agent-radio__description">
                      The platform suspends the agent when idle and wakes it on demand.
                    </span>
                  </span>
                </label>
              </div>
            </div>
          </div>
        )}

        {step === 1 && (
          <div className="cu-form-stack cu-agent-form-stack">
            {/* Capability discovery is enabled on this step, so its failure and Retry live here. */}
            <SubscriptionCapabilityNotice state={subscriptionCapabilities} />
            {grantInventoryLoading ? (
              <p className="cu-muted" role="status">
                Loading subscription options…
              </p>
            ) : null}
            {grantInventoryError ? (
              <div className="cu-banner cu-banner--error" role="alert">
                <span>{grantInventoryError}</span>
                <Button
                  type="button"
                  className="cu-btn--sm"
                  variant="ghost"
                  onClick={() => setInventoryRetryNonce(value => value + 1)}
                >
                  Retry
                </Button>
              </div>
            ) : null}
            {grantCatalogError ? (
              <div className="cu-banner cu-banner--error" role="alert">
                {grantCatalogError}
                <Button
                  type="button"
                  className="cu-btn--sm"
                  variant="ghost"
                  onClick={() => setInventoryRetryNonce(value => value + 1)}
                >
                  Retry
                </Button>
              </div>
            ) : null}
            <div className="cu-agent-access-section">
              <strong>LLM credentials</strong>
              <span className="cu-muted cu-agent-access-hint">
                Link an existing LLM Secret or create one for this agent.
              </span>
              <div className="cu-agent-radio-group">
                <label className="cu-agent-radio cu-agent-radio--card">
                  <input
                    type="radio"
                    checked={secretMode === 'existing'}
                    onChange={() => setSecretMode('existing')}
                  />
                  <span className="cu-agent-radio__copy">
                    <span className="cu-agent-radio__title">Use an existing LLM Secret</span>
                    <span className="cu-agent-radio__description">
                      Link a saved LLM Secret that already contains provider credentials.
                    </span>
                  </span>
                </label>
                <label className="cu-agent-radio cu-agent-radio--card">
                  <input
                    type="radio"
                    checked={secretMode === 'new'}
                    onChange={() => {
                      setSecretMode('new')
                      if (isOauthBrokerProvider(provider) && !llmPolicy?.fallbacks.length) {
                        setConnectionRef(CODEX_UNASSIGNED_CONNECTION_KEY)
                        setCodexModels([])
                        setGrokModels([])
                        setExistingSecret('')
                        setExistingLlmSecret('')
                        setProvider('openai')
                        setModelName(
                          resolveDefaultModel('openai', getModelOptions(allowedCatalog, 'openai'))
                        )
                      }
                    }}
                  />
                  <span className="cu-agent-radio__copy">
                    <span className="cu-agent-radio__title">Create a new LLM Secret</span>
                    <span className="cu-agent-radio__description">
                      Create a private LLM Secret for this agent. Its internal name is derived from
                      the agent name.
                    </span>
                  </span>
                </label>
              </div>
              {secretMode === 'existing' ? (
                <div className="cu-agent-access-section">
                  <strong>LLM Secret</strong>
                  <LlmSecretSelect
                    value={existingSecret}
                    placeholder="Select LLM Secret..."
                    options={secretOptions}
                    onChange={handleExistingSecretChange}
                  />
                  {isOauthBrokerProvider(provider) && chainRequiresSecret ? (
                    <>
                      <strong>LLM secret</strong>
                      <LlmSecretSelect
                        value={existingLlmSecret}
                        placeholder="Select secret..."
                        options={apiKeyOptions}
                        onChange={setExistingLlmSecret}
                      />
                    </>
                  ) : null}
                </div>
              ) : (
                <Field
                  description="Auto-named from the agent — edit the internal name if you prefer a different one."
                  label="LLM Secret name"
                >
                  <span className="cu-agent-input-shell">
                    <TextInput
                      value={newSecretName}
                      onChange={e => {
                        setSecretNameTouched(true)
                        setNewSecretName(toKebabInput(e.target.value))
                      }}
                      placeholder="llm-secret-name"
                    />
                    <span
                      className={cn(
                        'cu-agent-input-shell__status',
                        !toKebabCase(newSecretName) && 'cu-agent-input-shell__status--empty'
                      )}
                      aria-label={
                        toKebabCase(newSecretName)
                          ? 'Valid LLM Secret name'
                          : 'LLM Secret name empty'
                      }
                    >
                      {toKebabCase(newSecretName) ? <IconCheck width={16} height={16} /> : null}
                    </span>
                  </span>
                </Field>
              )}
            </div>
            <LlmProviderConfig
              provider={provider}
              model={modelName}
              onPrimaryChange={next => {
                setProvider(next.provider)
                setModelName(next.model)
                // A grant belongs to exactly one broker: any provider change
                // (Codex → Grok, broker → static) drops the selected grant, its
                // model catalog and the subscription pick so the next provider
                // never reads another broker's connection key.
                if (next.provider !== provider) {
                  setConnectionRef(CODEX_UNASSIGNED_CONNECTION_KEY)
                  setCodexModels([])
                  setGrokModels([])
                  if (parseCredentialSelect(existingSecret).kind === 'subscription') {
                    setExistingSecret('')
                  }
                }
              }}
              policy={llmPolicy}
              onPolicyChange={setLlmPolicy}
              allowedModels={allowedModels}
              onAllowedModelsChange={setAllowedModels}
              catalog={catalogForEditor}
              catalogLoading={modelsLoading}
              catalogError={modelsError}
              modelLabel="Default model"
              showAllowedModels={false}
              credentials={
                chainRequiresSecret && secretMode === 'new'
                  ? {
                      draft: llmKeyDraft,
                      onChange: (dataKey, value) =>
                        setLlmKeyDraft(prev => ({ ...prev, [dataKey]: value })),
                    }
                  : undefined
              }
              secretKeys={chainRequiresSecret && secretMode === 'new' ? llmSecretKeys : []}
              fallbackProvidersInitiallyCollapsed
              disabled={busy}
              grokEnabled={grokEnabled}
            />
          </div>
        )}

        {step === 2 && (
          <div className="cu-form-stack cu-agent-form-stack cu-agent-form-stack--wide">
            {directoryLoadError ? (
              <div className="cu-workflow-access__error" role="alert">
                <span>{directoryLoadError}</span>
                <Button
                  type="button"
                  className="cu-btn--sm"
                  variant="ghost"
                  onClick={() => void loadDirectory()}
                  disabled={busy || directoryLoading}
                >
                  {directoryLoading ? 'Retrying...' : 'Retry'}
                </Button>
              </div>
            ) : null}
            <div className="cu-agent-access-section">
              <div className="cu-agent-access-tabs" role="tablist" aria-label="Access type">
                <button
                  type="button"
                  className="cu-agent-access-tab"
                  role="tab"
                  aria-selected={accessTab === 'members'}
                  data-active={accessTab === 'members'}
                  onClick={() => setAccessTab('members')}
                >
                  {selectedUserIds.length > 0 ? <IconCheck width={14} height={14} /> : null}
                  <span>Members</span>
                  {selectedUserIds.length > 0 ? (
                    <span className="cu-agent-access-tab__count">{selectedUserIds.length}</span>
                  ) : null}
                </button>
                <button
                  type="button"
                  className="cu-agent-access-tab"
                  role="tab"
                  aria-selected={accessTab === 'teams'}
                  data-active={accessTab === 'teams'}
                  onClick={() => setAccessTab('teams')}
                >
                  {selectedTeamIds.length > 0 ? <IconCheck width={14} height={14} /> : null}
                  <span>Teams</span>
                  {selectedTeamIds.length > 0 ? (
                    <span className="cu-agent-access-tab__count">{selectedTeamIds.length}</span>
                  ) : null}
                </button>
              </div>
              {accessTab === 'members' ? (
                <div className="cu-workflow-access__picker cu-workflow-access__picker--inline">
                  <div data-testid="wizard-users-list">
                    <SelectionDropdown
                      id="wizard-member-picker"
                      inline
                      value={selectedUserIds}
                      onChange={setSelectedUserIds}
                      options={memberAccessOptions}
                      placeholder="Select members"
                      searchPlaceholder="Search members..."
                      selectionLabel="Selected members"
                      emptyLabel="No members available."
                      disabled={busy || directoryLoading}
                    />
                  </div>
                </div>
              ) : (
                <div className="cu-workflow-access__picker cu-workflow-access__picker--inline">
                  <div data-testid="wizard-teams-list">
                    <SelectionDropdown
                      id="wizard-team-picker"
                      inline
                      value={selectedTeamIds}
                      onChange={setSelectedTeamIds}
                      options={teamAccessOptions}
                      placeholder="Select teams"
                      searchPlaceholder="Search teams..."
                      selectionLabel="Selected teams"
                      emptyLabel="No teams available."
                      disabled={busy || directoryLoading}
                    />
                  </div>
                </div>
              )}
            </div>

            {selectedUserIds.length === 0 && selectedTeamIds.length === 0 && directoryLoadError ? (
              <p className="cu-agent-access-note" data-testid="wizard-empty-access-load-error-note">
                Directory access could not be loaded. You can continue now and grant access later
                from the agent detail page.
              </p>
            ) : selectedUserIds.length === 0 && selectedTeamIds.length === 0 ? (
              <p className="cu-agent-access-note" data-testid="wizard-empty-access-warning">
                No members or teams selected. You can continue and grant access later from the agent
                detail page.
              </p>
            ) : null}
          </div>
        )}

        {step === 3 && (
          <div className="cu-form-stack cu-agent-form-stack cu-agent-form-stack--wide">
            <div className="cu-agent-access-section">
              <strong>Connectors</strong>
              <span className="cu-muted cu-agent-access-hint">
                Choose the connectors this agent can use. You can leave this empty and add
                connectors later.
              </span>
            </div>
            <div className="cu-agent-mcp-grid" role="group" aria-label="Available connectors">
              {availableMcp.map(({ name, meta }) => (
                <CheckboxField
                  key={name}
                  checked={selectedMcp.includes(name)}
                  className="cu-agent-mcp-option"
                  label={
                    <span className="cu-agent-mcp-option__label">
                      <span className="cu-agent-mcp-option__name">{name}</span>
                      <span className="cu-agent-mcp-option__meta">{meta}</span>
                    </span>
                  }
                  disabled={busy}
                  onChange={() => toggleMcp(name)}
                />
              ))}
              {availableMcp.length === 0 ? (
                <span className="cu-agent-empty-note">No connectors available.</span>
              ) : null}
            </div>
            <div className="cu-agent-connectors-summary" aria-live="polite">
              <div className="cu-agent-connectors-summary__head">
                <span>Selected connectors</span>
                <span>{selectedMcp.length}</span>
              </div>
              {selectedMcp.length > 0 ? (
                <ul className="cu-agent-connectors-summary__list">
                  {[...selectedMcp]
                    .sort((a, b) => a.localeCompare(b))
                    .map(name => (
                      <li key={name}>{name}</li>
                    ))}
                </ul>
              ) : (
                <p className="cu-muted">
                  None selected. You can add connectors later from the agent detail page.
                </p>
              )}
            </div>
          </div>
        )}

        {error ? (
          <div className="cu-banner cu-banner--error cu-agent-flow-message">{error}</div>
        ) : null}
        {validationMessage && !canNext ? (
          <div className="cu-agent-validation-message">
            <IconAlertTriangle width={14} height={14} />
            {validationMessage}
          </div>
        ) : null}

        <div className={mode === 'page' ? 'cu-create-actions' : 'cu-modal-panel__foot'}>
          <Button
            onClick={() => setStep(s => Math.max(0, s - 1))}
            disabled={busy || step === 0}
            size="sm"
            variant="ghost"
          >
            Back
          </Button>
          {step < STEPS.length - 1 ? (
            <Button
              onClick={() => setStep(s => Math.min(STEPS.length - 1, s + 1))}
              disabled={busy || !canNext}
              size="sm"
              variant="primary"
            >
              Next
            </Button>
          ) : (
            <Button
              onClick={() => void submitAll()}
              disabled={busy || !canNext}
              size="sm"
              variant="primary"
            >
              {busy ? 'Saving…' : 'Create Agent'}
            </Button>
          )}
        </div>
      </CreateStepFlow>
    </>
  )

  const wizardContent =
    mode === 'page' && pageHeader ? (
      <CreateFlowPanel header={pageHeader}>{wizardBody}</CreateFlowPanel>
    ) : (
      <div
        className={
          mode === 'page' ? 'cu-agent-create-panel' : 'cu-modal-panel cu-agent-create-dialog'
        }
        role={mode === 'page' ? 'region' : 'dialog'}
        aria-labelledby="create-agent-title"
        onClick={mode === 'page' ? undefined : e => e.stopPropagation()}
      >
        {wizardBody}
      </div>
    )

  if (mode === 'page') {
    return wizardContent
  }

  return (
    <div
      className="cu-modal-backdrop"
      role="presentation"
      onClick={e => {
        if (e.target === e.currentTarget && !busy) onClose()
      }}
    >
      {wizardContent}
    </div>
  )
}